Skip to content

feat(i18n): add Traditional Chinese (zh-TW) locale support - #3916

Open
junhao-ye wants to merge 6 commits into
Tencent:mainfrom
junhao-ye:main
Open

junhao-ye wants to merge 6 commits into
Tencent:mainfrom
junhao-ye:main

Conversation

@junhao-ye

Copy link
Copy Markdown

概述

新增繁體中文(台灣)zh-TW 語系。

與 #2708 的關係

此 PR 延續 #2708 (@leonoxo) 的工作——leonoxo 自 2026-08-14 起做了 4 輪 rebase,
把 zh-TW key 從 6,036 補到 6,202,但 OPEN 7 週無 maintainer 回應。

本 PR 在他的基礎上重新跑了完整的 pipeline:key 數從 6,202 增至 6,547
(涵蓋 main 近期新增的 sandbox lifecycle / Serply provider / BM25 scoring 等),
並補上他在 #2708 沒處理的後端兩處功能性把關(詳下方)。

@leonoxo,請先看下方「建議的合併方式」段落,看哪個最合適再決定。

變更內容(6 commits)

  1. i18n(zh-TW): add Traditional Chinese (Taiwan) locale bundle (6,547 keys) — 機械產生自 zh-CN.ts
  2. i18n(zh-TW): register locale bundle in i18n infrastructure (5 → 6) — 9 檔
  3. i18n(zh-TW): fix normalizeEmbedLocale and add zh-TW embed block (514 keys) — 修原 startsWith('zh') 邏輯
  4. i18n(zh-TW): wire zh-TW into UI language pickers and TDesign locale — 5 個 UI 接點
  5. i18n(zh-TW): widen API union types and update tests for zh-TW — API 類型與 7 條 normalize 斷言
  6. i18n(zh-TW): add zh-TW to backend supportedLocales whitelist — 後端白名單

合計:23 檔變更、+8,433 / −9 行。

為何需要這個修改

  • UI:讓使用者能在語言切換器中選「繁體中文」,介面、偵測記錄、IM 回覆等所有 zh-TW 字串正確呈現。
  • 功能性把關(feat(i18n): add Traditional Chinese (zh-TW) locale support #2708 沒處理):
    • 後端白名單:internal/types/locale.go 的 supportedLocales 必須含 zh-TW,
      否則前端的 zh-TW 會被 NormalizeSupportedLocale 靜默丟成空字串 → 語言選擇器實際寫入無效值。
    • Embed 正規化:normalizeEmbedLocale 原實作 startsWith('zh') return 'zh-CN' 會把 zh-tw/zh-hk/zh-mo/zh-hant 全吞成簡體,
      本 PR 把繁中變體判定排在通用 zh 之前。

怎麼驗證(測試結果)

項目 結果
npm run check-i18n 13/13 ✅
npm run type-check (vue-tsc --build) 0 error ✅
骨架等價(挖空字串內容後逐字元比對) 183,406 字元逐字元相同 ✅
鍵集合 347/347 一致,零缺漏 ✅
Node 真實載入 6,547 leaves = 6,547 leaves,全部為字串 ✅
內嵌 zh-TW 區塊 514 leaves,骨架與 zh-CN 區塊一致 ✅
漏網盤查 0 MUST(用獨立觀察清單反掃輸出檔)

骨架等價證明「只轉值、不動鍵、不動結構、不動註解」——review 只需看 value 是否合台灣用語。

設計決策

  • 語言切換器標記用「繁」字,不用 🇹🇼 旗標:{ value: 'zh-TW', label: '繁體中文', shortLabel: '繁中', flag: '繁' }。
    理由:簡繁切換用「繁/簡」字標示是中文軟體的通行做法,語意清楚且無爭議。
    若 maintainer 偏好旗標 emoji,只需改 Login.vue 一行。
  • 交換映射:文档→文件 + 文件→檔案 並存,是語意正確的台灣用法,
    不是 bug。已用 5 條 selftest 釘死這組配對。
  • 新增 tw-terms.tsv:364 條生效詞條 + 26 條 never + 47 條保護詞,
    以 --selftest 66/66 守門。詞表本身隨本 PR 附上以供審查。

詞彙選擇(部分)

  • 智能體 → 智慧代理(保留與 feat(i18n): add Traditional Chinese (zh-TW) locale support #2708 一致)
  • 配置 → 設定(soft,本專案 332 處)
  • 文件 → 檔案、文档 → 文件(交換映射)
  • 知識庫 → 知識庫(同形同義)、檢索 → 檢索(同形同義)
  • 添加 → 新增、用戶 → 使用者、數據 → 資料、列表 → 清單、渲染 → 算繪

建議的合併方式

兩個選項請 @leonoxo 與 maintainer 擇一:

選項 A:保留 #2708 作者身份(最乾淨)

我把這個 branch rebase onto #2708 的 head d4317d37,保留你 6,202 keys + 我 6,547 keys 的合併 + backend 兩處修復。
PR author 改為你,這個新 PR 關閉(或併入你的)。

選項 B:以這個 PR 為主(最簡潔)

這個 PR 繼續走,description 已明確標註 #2708 與你的 contribution 作為「原作者貢獻」。
#2708 由 maintainer 自行決定關閉或保留。

@leonoxo 你 OK 哪個?

配套資產

  • tw-localization/:詞表 + 轉換器(可重用技能 i18n-zh-tw-localizer 已封裝在 ~/.workbuddy/skills/)
  • gen_zh_tw.py / wire_zh_tw.py / verify_zh_tw.py / review_misses.py:pipeline 工具鏈,
    可在 main 失穩時重跑整條(轉換→接線→驗證→盤查)

Checklist

  • check-i18n 全綠
  • vue-tsc --build 0 error
  • 骨架等價
  • Node 真實載入
  • 漏網盤查 0 MUST
  • 後端白名單
  • API 類型聯集
  • UI 接線(5 個語言選擇器入口)
  • 等待 fork CI 批准(fork PR 的特性,請 maintainer 觸發)

機械產生自 zh-CN.ts:以 zhconv (zh-tw) 為字形基底,詞彙層以 tw-terms.tsv(364 條生效詞條)覆寫,保留 26 條 never 與 47 條保護詞。骨架等價、鍵序列、Node 真實載入、內嵌區塊 四道檢查皆通過(詳見審計目錄)。
- resolveDefaultLocale.ts: SUPPORTED_LOCALES = ['zh-CN','zh-TW','en-US','ru-RU','ko-KR','ja-JP']
- i18n/index.ts: 載入 zhTW 並掛入 messages['zh-TW']
- localeKeyAudit.ts: 加入 LOCALE_BUNDLES['zh-TW'] 與測試守門(LOCALE_ORDER、emptyBundles)
- localeKeyAudit.test.ts: 把 zh-TW 補進期望清單
- locales/{en-US,ja-JP,ko-KR,ru-RU,zh-CN}.ts: language 區塊補 zhTW 顯示名(讓語言切換器正確顯示繁中選項)
…keys)

原實作 startsWith('zh') 直接命中 zh-TW/zh-HK/zh-Hant 並回傳 zh-CN
→ 繁中使用者將永遠看到簡體字串。修正後:
  - 繁中變體 (zh-tw/zh-hk/zh-mo/zh-hant) 排在通用 zh 之前,優先回傳 zh-TW
  - 內嵌 zh-TW 區塊加入 514 個字串,骨架與 zh-CN 區塊逐字元相同(只換區塊名)
- App.vue: 載入 tdesign-vue-next esm/zh_TW,tdLocaleMap['zh-TW'] = zhTWConfig
- Login.vue: 語言切換器新增 { value: 'zh-TW', label: '繁體中文', shortLabel: '繁中', flag: '繁' }
  (刻意不用旗標 emoji,改以「繁」字標示,語意清楚且無爭議)
- GeneralSettings.vue: 設定頁語言下拉新增 <t-option value='zh-TW' ...>
- AgentEmbedChannelPanel.vue: 代理嵌入頻道語言選單新增繁中
- IMChannelPanel.vue: IM 頻道語言選單新增繁中
- api/agent/index.ts: IMChannel.locale 聯合型別補 'zh-TW'
- api/embed/index.ts: EmbedLocaleTag 聯合型別補 'zh-TW'
- i18n/embedLocale.test.ts: supported-list 期望補上 zh-TW;新增 7 條 normalizeEmbedLocale 斷言(覆蓋 zh-tw / zh-hk / zh-mo / zh-hant / zh-Hant-TW 等變體正確路由到 zh-TW)
- locales/workspaceTerminology.test.ts: workspace 詞彙測試也對 zh-TW 做同樣的禁用詞斷言(與其他 locale 同步)
- internal/types/locale.go: supportedLocales["zh-TW"] = {}
  (NormalizeSupportedLocale 會靜默丟掉未列出的 tag,導致前端語言選擇器實際寫入空字串——
   此修正保證前端選 zh-TW 時 embed 預設語言與 IM 回覆語言會被後端接受)
- internal/types/locale_test.go: 期望清單補上 zh-TW
- internal/handler/mcp_usage_instructions.go: MCP 工具使用說明對照表新增 zh-TW → 'Traditional Chinese'
@leonoxo

leonoxo commented Oct 5, 2026

Copy link
Copy Markdown

@junhao-ye 你好,我是 #2708 的作者 leonoxo。感謝你在我的基礎上補全並推進,我這邊不再重複維護,請以你的 #3916 為主即可,#2708 可以關閉。也一併請維護者:zh-TW 這套 locale 目前 key 已補至最新、並含後端兩處判定修復,麻煩有閒暇時 review 合併,讓繁體中文正式納入官方版本。感謝!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants