語系清單¶

本檔角色：i18n 四語系 + 品牌副標 + 字典結構 + 社群 PR 流程。對應模組（實作）：程式架構/i18n.md。

1. 支援語系¶

LangCode	名稱	預設
`zh-TW`	繁體中文（台灣）	✅ 預設
`zh-CN`	简体中文
`en`	English	Fallback
`ja`	日本語

DEFAULT_LANG: 'zh-TW'
FALLBACK_LANG: 'en'
SUPPORTED_LANGS: ['zh-TW', 'zh-CN', 'en', 'ja']

2. 品牌副標（4 語系統一）¶

key	用途	zh-TW	zh-CN	en	ja
`app.brand`	logo / nav	Open4WD	Open4WD	Open4WD	Open4WD
`app.tagline`	核心副標（3–8 字）	去中心化四驅競速	去中心化四驱竞速	Decentralized 4WD Racing	分散型 4WD レーシング
`app.description`	meta description（~150 字元）	開源、點對點的四驅競速平台，瀏覽器即可遊玩。創作者打造自製車輛、賽道與武器，最多支援 8 人混戰。	开源、点对点的四驱竞速平台，浏览器即可游玩。创作者打造自制车辆、赛道与武器，最多支持 8 人混战。	Open-source, peer-to-peer 4WD racing platform playable in your browser. UGC creators build cars, tracks, and weapons. Up to 8-player FFA.	ブラウザで遊べる、オープンソースの P2P 型 4WD レーシングプラットフォーム。クリエイターがマシン、トラック、武器を制作。最大 8 人のフリー・フォー・オール。

翻譯規則：app.brand 跨語系統一不翻；其他 keys 採對應語系。

3. 字典檔案結構¶

src/i18n/
├── zh-TW.json       ← 預設 + 完整翻譯
├── zh-CN.json
├── en.json
├── ja.json
└── index.ts         ← I18nService 實作

每檔 JSON 的 root key 必須與完整撰寫源 zh-TW.json 相同；現行共 19 個：

{
  "materials": {},
  "app": { /* 品牌副標 */ },
  "common": { /* 通用 UI 字串 */ },
  "race": { /* 比賽相關 */ },
  "garage": { /* 車庫相關 */ },
  "settings": { /* 設定頁 */ },
  "errors": { /* 錯誤訊息（含領域錯誤碼映射：errors.keyManager.* 等） */ },
  "submit": {},
  "chat": {},
  "themes": { /* 主題分類顯示名（主題系統.md §4） */ },
  "validation": { /* 表單檢核錯誤（validation.required / validation.range 帶 {min}/{max}…；ui-frontend.md §4.1） */ },
  "skills": {},
  "nav": {},
  "sort": {},
  "stats": {},
  "ugc": {},
  "parts": {},
  "pages": {},
  "seo": {}
}

詳見程式架構/i18n.md §1。

4. I18nService 介面¶

介面定義見程式架構/i18n.md §2。

4.1 翻譯範例¶

t('race.lap', { lap: 1, total: 3 })
// zh-TW: "第 1 圈 / 共 3 圈"
// en:    "Lap 1 / 3"

5. Angular Pipe¶

詳見程式架構/i18n.md §3：

<p>{{ 'common.confirm' | i18n }}</p>
<p>{{ 'race.lap' | i18n: { lap: 1, total: 3 } }}</p>

6. 啟動時策略¶

1. URL 帶 `/<lang>/` 前綴（SEO 登陸）→ 以該語系為準（剝前綴、導向無前綴路由，[程式架構.md §13](程式架構.md)）
2. 否則讀已持久化的顯示語系設定（settings `DisplaySettings.language`，未選＝null）
3. 若無 → 偵測 navigator.language
4. 對應到 SUPPORTED_LANGS（fallback 到 en）
5. 載入該語系字典（lazy load = runtime 載入記憶體）
6. 字典 chunk 隨 bundle 交付、SW install 全量 precache 涵蓋（[程式架構/i18n.md §6](程式架構/i18n.md)）
7. 只載入目前 CJK 語系的 400／700 字型 stylesheet；英文保持初始 Inter（[程式架構/i18n.md §6.1](程式架構/i18n.md)）

7. PWA 字典快取¶

詳見程式架構/i18n.md §6：

Service Worker cache-first 策略（字典隨 bundle chunk、install 全量 precache 涵蓋）
字典 chunk 命中本地快取，無 network 也可離線顯示
升版時依 client_version 失效快取

8. 複數 / 日期 / 數字格式化¶

詳見程式架構/i18n.md §3（ICU 複數）· §4（日期 / 數字 / 金額）：

場景	處理
複數	ICU MessageFormat (`{count, plural, one {# 圈} other {# 圈}}`)
日期	`Intl.DateTimeFormat(lang, options)`
數字	`Intl.NumberFormat(lang)`
金額	minor units（`bigint`）÷ 100 → 顯示幣、兩位小數（1 幣 = 100 minor units；程式架構/economy.md `formatCurrency`）

9. 設定頁切換¶

設定頁顯示語系選單；切換後：

寫入 settings 的 DisplaySettings.language（不另設 localStorage 語系鍵）
顯示「需重整才生效」提示，不立即換目前字典、router 或字型
玩家在安全時機重整；bootstrap 依新設定載入 lazy dictionary chunk 與對應 locale font（程式架構/i18n.md §5）

10. 社群 PR 流程¶

詳見程式架構/i18n.md §7。歡迎社群貢獻：

1. Fork repo
2. 新增 src/i18n/<lang>.json
3. 對齊現有 keys 結構
4. 跑 schema 驗證 (`pnpm run i18n:validate`)
5. 提 PR
6. 通過 review → merge
7. patch bump（純資源變更）

10.1 新增語系流程¶

新增第 5 語系：

加入 SUPPORTED_LANGS ＋更新 LangCode union（程式架構/i18n.md §2）
新增 <lang>.json
補對應 hreflang URL '/<lang>/'（HREFLANG_MAP）
同步 SSG routes / sitemap 語系來源（程式架構/seo.md §4/§6）
補 OG image localization（若有）
patch bump

不影響配對（純資源變更）。

11. 字典 Schema 驗證¶

詳見程式架構/i18n.md §7：

用 JSON Schema 驗證每個字典檔結構一致（基準 = zh-TW，撰寫源）
CI 跑 pnpm run i18n:validate
缺 key → 警告（fallback to en）；en 缺 key → error（en 是 fallback 鏈前提，不完整會露 raw key）
多 key → 警告（dead translation）

12. SEO hreflang¶

HREFLANG_MAP 見 ui.md §16 / 部署資訊.md §7.2。

每頁面對應 hreflang 連結。

13. 缺漏翻譯策略¶

情況	處理
玩家當前語系缺 key	fallback to en
en 也缺 key	dev 顯示 raw key、production 顯示 `[key]`
翻譯字串含 `{param}` 但呼叫未傳該參數	保留顯示 `{param}` placeholder（除錯友善）

14. 升版影響¶

新增 / 修改 key → patch bump（純資源）
結構性變更（split / merge keys）→ 仍 patch（refactor 類；src/i18n/ 依 path 表無條件 patch，版本規範.md §4）
不影響 deterministic / protocol（純客戶端）

詳見版本規範.md §3。

15. 不收錄語系¶

目前不收錄：

韓文（ko）：等社群 PR
法 / 德 / 西文：等社群 PR
其他：等社群 PR

PR 流程同 §10。

16. 跨模組對接¶

模組	內容
程式架構/i18n.md	服務實作 / ICU 複數 / 格式化 / 快取 / schema 驗證
程式架構/settings.md	設定頁語系切換 UI
程式架構/seo.md	hreflang / 多語系 metadata
程式架構/pwa-offline.md	SW 字典快取（§7）
`system-constants/ui/i18n-defaults`	`DEFAULT_LANG` / `SUPPORTED_LANGS` 等常數（值的權威 = ui.md §15）