Merge pull request #1430 from bilawalsidhu/codex/hal-646-zh-hant

i18n: add Chinese (Traditional) zh-Hant (#1430)

Co-authored-by: Enzo Abyie <[email protected]>
Co-authored-by: EDIT-Aeterna <[email protected]>
Co-authored-by: caxer <[email protected]>
Co-authored-by: tbdavid2019 <[email protected]>

changelog.d/1430-traditional-chinese.md

@@ -0,0 +1,4 @@
+- Add Traditional Chinese (zh-Hant) with language selection and localized
+  Chinese readouts: the Simplified Chinese catalog written in Traditional
+  characters, based on translations by @abiyeenzo (#914) and @EDIT-Aeterna
+  (#979) (German, @gekh, #1430).

docs/CURRENT-STATE.md

@@ -3733,7 +3733,7 @@ test:track` 43 tracking invariants · headless QA harnesses under
 
 ### Interface localization (October 2026)
 
-Shipped locales: **en** (source and fallback), **es**, **ru** and **zh-CN**. The code lives in
+Shipped locales: **en** (source and fallback), **es**, **ru**, **zh-CN** and **zh-Hant**. The code lives in
 `src/i18n/`. How to mark UI text: [`docs/I18N.md`](./I18N.md); translator workflow:
 [`docs/TRANSLATORS.md`](./TRANSLATORS.md).
 
@@ -3744,8 +3744,8 @@ Shipped locales: **en** (source and fallback), **es**, **ru** and **zh-CN**. The
   value). English has no catalog; every other locale is
   `src/i18n/locales/<code>.json`, and a missing entry falls back to English.
 - **Locale choice.** `?lang=` → stored choice (`gev:locale:v1`) →
-  `navigator.languages` → English. Chinese tags map to `zh-CN`; tags containing
+  `navigator.languages` → English. Chinese tags default to `zh-CN`; Traditional Chinese tags
-  `Hant`, `TW`, `HK` or `MO` are skipped. `?lang=` is not stored, and share links drop
+  select `zh-Hant`. Explicit `Hans` selects `zh-CN` regardless of region. `?lang=` is not stored, and share links drop
   it, so a recipient keeps their own language. The globe picker in the
   bottom-right corner (`src/ui/localePicker.js`) stores the choice, drops
   `?lang=` (keeps it only when storage is blocked) and reloads. It asks first

docs/TRANSLATORS.md

@@ -1,6 +1,6 @@
 # Translating God's Eye View
 
-Shipped languages: **English** (source and fallback), **Spanish** (`es`), **Russian** (`ru`) and **Simplified Chinese** (`zh-CN`).
+Shipped languages: **English** (source and fallback), **Spanish** (`es`), **Russian** (`ru`), **Simplified Chinese** (`zh-CN`) and **Traditional Chinese** (`zh-Hant`).
 
 ## How it works
 
@@ -63,4 +63,4 @@ These are contracts, not copy: layer ids and registry keys, status enums and oth
 
 ## Language notes
 
-Each language keeps its glossary, plural forms, units and style in its own file, `docs/translations/<code>.md`: [Spanish](./translations/es.md), [Russian](./translations/ru.md), [Simplified Chinese](./translations/zh-CN.md). Read it before translating, and add a term there when you settle on one.
+Each language keeps its glossary, plural forms, units and style in its own file, `docs/translations/<code>.md`: [Spanish](./translations/es.md), [Russian](./translations/ru.md), [Simplified Chinese](./translations/zh-CN.md), [Traditional Chinese](./translations/zh-Hant.md). Read it before translating, and add a term there when you settle on one.

docs/translations/zh-Hant.md

@@ -0,0 +1,17 @@
+# Traditional Chinese (`zh-Hant`)
+
+Catalog: `src/i18n/locales/zh-Hant.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
+
+`zh-Hant` is the Simplified Chinese catalog (`zh-CN`, credited to abiyeenzo, #914, and EDIT-Aeterna, #979) written in Traditional characters with OpenCC character conversion. Wording and terminology are the same as in `zh-CN`: change a term in [zh-CN.md](./zh-CN.md) and the `zh-CN` catalog first, then convert. Only the script differs.
+
+After `s2tw` conversion, fix the characters OpenCC picks wrongly: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道, 發佈 → 發布, 公佈 → 公布.
+
+## Style
+
+- Follow [zh-CN.md](./zh-CN.md) for wording, punctuation, spacing, units and the glossary, written in Traditional characters.
+- Relative-time placeholders may already include 前. In `LIVE · updated {age}`, the caller supplies the complete relative age; do not append another 前.
+- The picker displays 中文（繁體） / Chinese (Traditional); explicit Hans tags select Simplified Chinese.
+
+## Plurals
+
+`Intl.PluralRules('zh-Hant')` uses only `other`. Keep the measure words of the `zh-CN` entry: 「{count} 架飛機」、「{count} 艘船」.

scripts/package-boundaries.json

@@ -441,7 +441,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -480,7 +481,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -510,6 +512,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/ui/keyGuidance.js",
       "src/ui/statusText.js",
@@ -530,7 +533,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -546,7 +550,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -566,6 +571,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/ui/statusBadge.js"
     ],
@@ -592,6 +598,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/layerNames.js"
     ],
     "external": []
@@ -626,6 +633,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -642,6 +650,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": []
@@ -800,6 +809,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/ui/keyGuidance.js",
       "src/ui/layerNames.js",
@@ -921,6 +931,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -988,6 +999,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -1035,7 +1047,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1097,7 +1110,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1127,6 +1141,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/layers/recentImagery/display.js"
     ],
@@ -1156,7 +1171,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1187,6 +1203,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium", "satellite.js"]
@@ -1219,7 +1236,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1262,6 +1280,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/layers/installations/classLabel.js"
     ],
     "external": ["cesium", "@mapbox/vector-tile", "pbf"]
@@ -1298,6 +1317,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -1347,7 +1367,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium", "pbf", "@mapbox/vector-tile"]
   },
@@ -1376,7 +1397,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1424,7 +1446,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["hls.js", "cesium"]
   },
@@ -1488,6 +1511,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/layers/streetLevel/providers/mapillary/policy.js"
     ],
     "external": ["cesium", "pbf", "@mapbox/vector-tile", "mapillary-js"]
@@ -1516,7 +1540,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium", "@mapbox/vector-tile", "pbf"]
   },
@@ -1556,7 +1581,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1578,7 +1604,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1634,7 +1661,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -1697,6 +1725,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/statusText.js",
       "src/voice/providerCommands.js",
       "src/voice/providerCapabilities.js",
@@ -2579,6 +2608,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/layers/recentImagery/display.js",
       "src/ui/keyGuidance.js",
@@ -3163,6 +3193,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js",
       "src/layers/recentImagery/display.js",
       "src/layers/installations/classLabel.js",
@@ -3273,6 +3304,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/i18n/index.js"
     ],
     "external": ["cesium"]
@@ -3295,7 +3327,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -3332,6 +3365,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/scopeMaskPolicy.js",
       "src/ui/displayControls.js"
     ],
@@ -3357,7 +3391,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": []
   },
@@ -3449,6 +3484,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/unitLabels.js"
     ],
     "external": ["cesium"]
@@ -3504,6 +3540,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/statusText.js",
       "src/voice/providerCapabilities.js"
     ],
@@ -3757,7 +3794,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium", "egm96-universal", "pbf"]
   },
@@ -3800,7 +3838,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium", "pbf"]
   },
@@ -3853,7 +3892,8 @@
       "src/i18n/locale.js",
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
-      "src/i18n/locales/zh-CN.json"
+      "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json"
     ],
     "external": ["cesium"]
   },
@@ -3870,6 +3910,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/statusText.js",
       "src/ui/layerNames.js"
     ],
@@ -3929,6 +3970,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/data/geoImportImages.js",
       "src/data/geoImportPins.js",
       "src/layers/streetLevel/tileMath.js",
@@ -4125,6 +4167,7 @@
       "src/i18n/locales/es.json",
       "src/i18n/locales/ru.json",
       "src/i18n/locales/zh-CN.json",
+      "src/i18n/locales/zh-Hant.json",
       "src/ui/statusText.js",
       "src/ui/layerNames.js"
     ],

src/hudLocalityFormat.js

@@ -16,7 +16,8 @@ export function hudQuantity(value, unit, digits = 0) {
     maximumFractionDigits: digits,
   });
   const label = unitLabel(unit);
-  if (getLocale() === 'zh-CN') return label ? `${number} ${label}` : number;
+  if (getLocale().startsWith('zh-'))
+    return label ? `${number} ${label}` : number;
   return `${number}${label.toUpperCase()}`;
 }
 

src/i18n/firms-live-zh.test.mjs

@@ -5,12 +5,12 @@ import { createModel } from '../layers/firms/model.js';
 import { createQueries } from '../layers/firms/queries.js';
 
 const cases = [
-  [0, '不到 1 分钟前', '<1m ago'],
+  [0, '不到 1 分钟前', '<1m ago', '不到 1 分鐘前'],
-  [120000, '2 分钟前', '2m ago'],
+  [120000, '2 分钟前', '2m ago', '2 分鐘前'],
-  [7200000, '2 小时前', '2h ago'],
+  [7200000, '2 小时前', '2h ago', '2 小時前'],
 ];
 
-for (const [age, zh, en] of cases) {
+for (const [age, zh, en, hant] of cases) {
   test(`FIRMS live age ${age} ms has one relative-time suffix`, (context) => {
     const now = 1800000000000;
     context.mock.method(Date, 'now', () => now);
@@ -36,6 +36,8 @@ for (const [age, zh, en] of cases) {
       assert.equal(methods.getStats().loadingLabel, `LIVE · updated ${en}`);
       setLocale('zh-CN');
       assert.equal(methods.getStats().loadingLabel, `实时 · 更新于 ${zh}`);
+      setLocale('zh-Hant');
+      assert.equal(methods.getStats().loadingLabel, `實時 · 更新於 ${hant}`);
     } finally {
       setLocale(previousLocale);
     }

src/i18n/i18n.test.mjs

@@ -35,12 +35,18 @@ test('normalizeLocale folds regional variants and rejects unshipped tags', () =>
   assert.equal(normalizeLocale(' RU '), 'ru');
   assert.equal(normalizeLocale('en_GB'), 'en');
   assert.equal(normalizeLocale('xx'), null);
-  // Simplified Chinese by default; Traditional tags wait for zh-TW.
+  // Explicit script tags take precedence over regional defaults.
   assert.equal(normalizeLocale('zh'), 'zh-CN');
   assert.equal(normalizeLocale('zh-CN'), 'zh-CN');
   assert.equal(normalizeLocale('zh-Hans-SG'), 'zh-CN');
-  assert.equal(normalizeLocale('zh-TW'), null);
+  assert.equal(normalizeLocale('zh-Hant'), 'zh-Hant');
-  assert.equal(normalizeLocale('zh-Hant-HK'), null);
+  assert.equal(normalizeLocale(' ZH_hant '), 'zh-Hant');
+  assert.equal(normalizeLocale('zh-TW'), 'zh-Hant');
+  assert.equal(normalizeLocale('zh-Hant-HK'), 'zh-Hant');
+  assert.equal(normalizeLocale('zh-Hans-HK'), 'zh-CN');
+  assert.equal(normalizeLocale('zh-Hant-CN'), 'zh-Hant');
+  assert.equal(normalizeLocale('zh_HK'), 'zh-Hant');
+  assert.equal(normalizeLocale('zh-MO'), 'zh-Hant');
   assert.equal(normalizeLocale(undefined), null);
 });
 

src/i18n/index.js

@@ -19,8 +19,9 @@ import {
 import es from './locales/es.json' with { type: 'json' };
 import ru from './locales/ru.json' with { type: 'json' };
 import zhCN from './locales/zh-CN.json' with { type: 'json' };
+import zhHant from './locales/zh-Hant.json' with { type: 'json' };
 
-const CATALOGS = Object.freeze({ es, ru, 'zh-CN': zhCN });
+const CATALOGS = Object.freeze({ es, ru, 'zh-CN': zhCN, 'zh-Hant': zhHant });
 
 let currentLocale = DEFAULT_LOCALE;
 

src/i18n/locale.js

@@ -8,14 +8,15 @@ export const LOCALE_STORAGE_KEY = 'gev:locale:v1';
 export const DEFAULT_LOCALE = 'en';
 
 /** Shipped locales; order does not matter. Adding one: docs/TRANSLATORS.md. */
-export const LOCALES = Object.freeze(['en', 'es', 'ru', 'zh-CN']);
+export const LOCALES = Object.freeze(['en', 'es', 'ru', 'zh-CN', 'zh-Hant']);
 
 /** Each locale named in its own language, for the selector. */
 export const LOCALE_NAMES = Object.freeze({
   en: 'English',
   es: 'Español',
   ru: 'Русский',
-  'zh-CN': '简体中文',
+  'zh-CN': '中文（简体）',
+  'zh-Hant': '中文（繁體）',
 });
 
 /** Right-to-left locales. */
@@ -23,17 +24,19 @@ const RTL_LOCALES = Object.freeze([]);
 
 /**
  * Map any language tag to a shipped locale: 'ru-RU' and 'RU' → 'ru',
- * 'zh', 'zh-CN' and 'zh-Hans-SG' → 'zh-CN'.
+ * 'zh', 'zh-CN' and 'zh-Hans-SG' → 'zh-CN';
+ * 'zh-Hant', 'zh-TW', 'zh-HK' and 'zh-MO' → 'zh-Hant'.
  * @returns {string|null}
  */
 export function normalizeLocale(candidate) {
   if (typeof candidate !== 'string') return null;
   const [primary, ...rest] = candidate.trim().toLowerCase().split(/[-_]/);
-  // Traditional Chinese readers are not given Simplified: no zh-TW yet.
+  if (primary === 'zh') {
-  if (primary === 'zh')
+    if (rest.includes('hans')) return 'zh-CN';
     return rest.some((part) => ['hant', 'tw', 'hk', 'mo'].includes(part))
-      ? null
+      ? 'zh-Hant'
       : 'zh-CN';
+  }
   return LOCALES.includes(primary) ? primary : null;
 }
 

src/i18n/same-as-english.json

@@ -198,5 +198,62 @@
     "ΔE",
     "ΔN",
     "▲ {frp} MW"
+  ],
+  "zh-Hant": [
+    "1090 MHz",
+    "978 MHz UAT",
+    "AIS: --",
+    "AIS: {name}",
+    "BRG {value}°",
+    "BRG —",
+    "CAL {value}",
+    "CAL · {badge}",
+    "CCTV",
+    "CRS {value}°",
+    "CRT",
+    "FLIR",
+    "FOV",
+    "FOV {value}°",
+    "FT",
+    "GEO",
+    "HDG",
+    "HDG {value}°",
+    "House",
+    "Ironbow",
+    "KTS",
+    "Landsat 8/9",
+    "MM",
+    "NVG",
+    "REC",
+    "SRC {value}",
+    "S2 GhostMaps",
+    "S2 · {name}",
+    "Sentinel-2",
+    "Techno",
+    "Trance",
+    "USB {rate} msg/s",
+    "WHOT/BHOT",
+    "dB",
+    "ft",
+    "hPa",
+    "hemisphere|E",
+    "hemisphere|N",
+    "hemisphere|S",
+    "hemisphere|W",
+    "km",
+    "km/h",
+    "kt",
+    "kts",
+    "mph",
+    "{city} CCTV",
+    "{rate} msg/s",
+    "{source} HTTP {status}",
+    "{speed} kn",
+    "{type}  SPD: {speed}  HDG: {heading}",
+    "{value} KM",
+    "{value} KM/S",
+    "ΔE",
+    "ΔN",
+    "▲ {frp} MW"
   ]
 }

src/i18n/zh-Hant-display.test.mjs

@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { setLocale, t, tn, getLocale } from './index.js';
+import {
+  resolveLocale,
+  LOCALE_STORAGE_KEY,
+  writeStoredLocale,
+  applyDocumentLanguage,
+} from './locale.js';
+import { hudQuantity, LOCALIZED_LOCALITY } from '../hudLocalityFormat.js';
+import { formatCockpitDistance } from '../ui/cockpitPresentation.js';
+import { READOUT_WORDS } from '../layers/recentImagery/display.js';
+import { cctvSourceStatusLabel } from '../ui/cctvFrames.js';
+
+test('Traditional Chinese resolves from URL, saved preference and browser language', () => {
+  assert.equal(
+    resolveLocale({
+      location: { search: '?lang=zh-TW' },
+      storage: { getItem: () => 'en' },
+      languages: ['en'],
+    }),
+    'zh-Hant',
+  );
+  assert.equal(
+    resolveLocale({
+      location: { search: '' },
+      storage: {
+        getItem: (key) => (key === LOCALE_STORAGE_KEY ? 'zh-TW' : null),
+      },
+      languages: ['en'],
+    }),
+    'zh-Hant',
+  );
+  assert.equal(
+    resolveLocale({
+      location: { search: '' },
+      storage: { getItem: () => null },
+      languages: ['zh-Hant', 'en'],
+    }),
+    'zh-Hant',
+  );
+});
+
+test('Traditional Chinese persists and exposes the script locale for legacy choices', () => {
+  const stored = new Map();
+  assert.equal(
+    writeStoredLocale('zh-TW', {
+      setItem: (key, value) => stored.set(key, value),
+    }),
+    true,
+  );
+  assert.equal(stored.get(LOCALE_STORAGE_KEY), 'zh-Hant');
+  const doc = { documentElement: {} };
+  assert.equal(applyDocumentLanguage(doc, 'zh-TW'), true);
+  assert.equal(doc.documentElement.lang, 'zh-Hant');
+  assert.equal(doc.documentElement.dir, 'ltr');
+});
+
+test('Traditional Chinese readouts preserve unit case, coordinates and natural relative dates', () => {
+  const previous = getLocale();
+  try {
+    setLocale('zh-Hant');
+    assert.equal(hudQuantity(2069, 'km', 1), '2069.0 km');
+    assert.equal(formatCockpitDistance(14000), '14\u00a0km');
+    assert.equal(
+      LOCALIZED_LOCALITY.sector({ latDeg: 21.33, lonDeg: -77.5 }),
+      '扇區 21.33N 77.50W',
+    );
+    assert.equal(READOUT_WORDS.daysAgo(9), '9 天前');
+    assert.equal(READOUT_WORDS.daysAgo(0), '今天');
+    assert.equal(cctvSourceStatusLabel('ok'), '正常');
+    assert.equal(t('SAVE KEYS'), '保存密鑰');
+    assert.equal(
+      tn(2, 'Click {count} more point.', 'Click {count} more points.'),
+      '再點擊 2 個點。',
+    );
+  } finally {
+    setLocale(previous);
+  }
+});

src/layers/recentImagery/display.js

@@ -33,7 +33,9 @@ export const READOUT_WORDS = Object.freeze({
   date: (day) => displayDay(day, LONG_DAY),
   daysAgo: (delta) => {
     const text = formatRelativeTime(delta > 0 ? -delta : 0, 'day');
-    return getLocale() === 'zh-CN' ? text.replace(/(\d)(?=天)/g, '$1 ') : text;
+    return getLocale().startsWith('zh-')
+      ? text.replace(/(\d)(?=天)/g, '$1 ')
+      : text;
   },
   // "Sentinel-2" never breaks at its hyphen: a word joiner follows it
   // (JetBrains Mono has no U+2011 non-breaking hyphen).

src/ui/cockpitContext.js

@@ -15,7 +15,7 @@ const LOCALIZED_CONTEXT_SCOPE = Object.freeze({
   window: ({ label, radiusKm }) =>
     t('{label} · {radius} AIR/SEA WINDOW', {
       label,
-      radius: `${radiusKm === null ? '—' : formatNumber(radiusKm)}\u00a0${getLocale() === 'zh-CN' ? unitLabel('km') : unitLabel('km').toUpperCase()}`,
+      radius: `${radiusKm === null ? '—' : formatNumber(radiusKm)}\u00a0${getLocale().startsWith('zh-') ? unitLabel('km') : unitLabel('km').toUpperCase()}`,
     }),
   installations: ({ scope, coverage }) =>
     t('{scope} · INSTALLATIONS {coverage}', { scope, coverage }),

src/ui/cockpitPresentation.js

@@ -149,7 +149,7 @@ export function formatCockpitDistance(distanceM) {
     minimumFractionDigits: digits,
     maximumFractionDigits: digits,
   });
-  return getLocale() === 'zh-CN' ? distance : distance.toUpperCase();
+  return getLocale().startsWith('zh-') ? distance : distance.toUpperCase();
 }
 
 export function formatCockpitWindDirection(value) {

src/ui/localePicker.js

@@ -20,6 +20,11 @@ export const LOCALE_SEARCH_THRESHOLD = 8;
 /** Type-ahead keystrokes closer together than this extend one prefix. */
 export const TYPEAHEAD_RESET_MS = 500;
 
+const CHINESE_LABELS = {
+  'zh-CN': 'Chinese (Simplified)',
+  'zh-Hant': 'Chinese (Traditional)',
+};
+
 /**
  * Text folded for search: no diacritics, lower case. 'Español' → 'espanol',
  * 'Ёжик' → 'ежик'.
@@ -464,12 +469,13 @@ export function mountLocalePicker({
     item.dataset.locale = option.code;
     const name = element(documentRef, 'span', 'locale-picker-native');
     name.textContent = option.nativeName;
-    // Every row reads the same: the language named in itself, then its code.
+    // Chinese variants are distinguished by script rather than region.
-    // The interface-language name only helps the search find it.
     const meta = element(documentRef, 'span', 'locale-picker-meta');
     const codeLabel = element(documentRef, 'span', 'locale-picker-option-code');
     codeLabel.setAttribute('translate', 'no');
-    codeLabel.textContent = option.code.toUpperCase();
+    codeLabel.textContent =
+      CHINESE_LABELS[option.code] || option.code.toUpperCase();
+    if (CHINESE_LABELS[option.code]) codeLabel.lang = 'en';
     meta.append(codeLabel);
     const text = element(documentRef, 'span', 'locale-picker-text');
     text.append(name, meta);

src/ui/localePicker.test.mjs

@@ -40,7 +40,7 @@ test('the current language comes first, the rest by their own names', () => {
         nativeNames: LOCALE_NAMES,
       }),
     ),
-    ['ru', 'en', 'es', 'zh-CN'],
+    ['ru', 'en', 'es', 'zh-CN', 'zh-Hant'],
   );
   assert.deepEqual(
     codes(
@@ -50,7 +50,7 @@ test('the current language comes first, the rest by their own names', () => {
         nativeNames: LOCALE_NAMES,
       }),
     ),
-    ['es', 'en', 'ru', 'zh-CN'],
+    ['es', 'en', 'ru', 'zh-CN', 'zh-Hant'],
   );
   assert.deepEqual(
     codes(
@@ -60,7 +60,7 @@ test('the current language comes first, the rest by their own names', () => {
         nativeNames: LOCALE_NAMES,
       }),
     ),
-    ['en', 'es', 'ru', 'zh-CN'],
+    ['en', 'es', 'ru', 'zh-CN', 'zh-Hant'],
   );
   const rows = buildLocaleOptions({
     locales: MANY,
@@ -263,7 +263,7 @@ test('keyboard model: open on the current language, move, choose, close', () =>
   assert.deepEqual(model.keydown({ key: 'ArrowDown' }), { handled: true });
   assert.equal(model.activeOption.code, 'en');
   model.keydown({ key: 'End' });
-  assert.equal(model.activeOption.code, 'zh-CN');
+  assert.equal(model.activeOption.code, 'zh-Hant');
   model.keydown({ key: 'Home' });
   assert.equal(model.activeOption.code, 'ru');
   model.keydown({ key: 'ArrowUp' });