I18n 專家
總覽
提供完整的 i18n 設定與稽核流程:設定 i18n 框架、將使用者面向的字串取代為金鑰、確保語言檔對等性,並針對 en-US 與 zh-CN 驗證複數規則與格式化。
核心能力
- 函式庫選擇與設定(React、Next.js、Vue)。
- 金鑰架構與語言檔組織方式。
- 翻譯生成與品質策略(AI、專業、人工)。
- 路由與語言偵測/切換。
- SEO 與中繼資料本地化(適用時)。
- RTL 支援(僅限範圍內包含 RTL 語言時)。
範圍輸入(若不明確請詢問)
- 框架與路由風格。
- 現有 i18n 狀態(無、部分、舊版)。
- 目標語言(預設:en-US + zh-CN)。
- 翻譯品質需求(AI vs 專業 vs 人工)。
- 使用的語言檔格式(JSON、YAML、PO、XLIFF)。
- 正式度/文化需求(若有的話)。
工作流程(稽核 -> 修復 -> 驗證)
- 確認範圍與語言目標
- 識別 i18n 框架與語言檔位置。
- 確認語言;指定時預設為 en-US + zh-CN。
- 設定 i18n 基線(若缺少)
- 選擇適合框架的函式庫(例如 React:react-i18next;Next.js:next-intl;Vue:vue-i18n)。
- 安裝套件並建立 i18n 進入點/設定檔。
- 在應用程式根目錄注入 Provider 並載入語言資源。
- 新增語言切換器與持久化機制(路由/參數/localStorage,依情況而定)。
- 建立語言檔佈局與金鑰命名空間。
- 若路由支援語言感知,應及早定義語言區段策略(子路徑、子網域、查詢參數)。
- 若有使用者面向的中繼資料,請包含標題/描述的翻譯。
- 稽核金鑰使用情況與語言對等性
- 執行:
python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json> - 將缺少的金鑰/對等性差距視為阻擋事項。
- 手動驗證動態金鑰(
t(var))。
- 尋找原始的面向使用者字串
- 搜尋:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - 本地化無障礙標籤。
- 將字串取代為金鑰
- 對 UI 文字使用
t('namespace.key')。 - 對複數形式使用
t('key', { count })與_one/_other金鑰。 - 對時間/日期/數字使用 Intl/應用程式格式化器。
- 本地化錯誤處理(關鍵)
- 將錯誤碼對應到本地化金鑰;僅顯示本地化 UI。
- 僅在日誌中記錄原始錯誤詳細資訊。
- 對未知錯誤碼提供本地化後備方案。
- 更新語言檔
- 在兩種語言中新增缺少的金鑰。
- 保持佔位符一致;除非要求,否則避免重新命名。
- 使用約定的方法生成翻譯;保留佔位符與複數規則。
- 驗證
- 重新執行稽核,直到缺少/對等性問題為零。
- 驗證 JSON(例如
python -m json.tool <file>)。 - 更新斷言可見文字的測試。
防護措施
- 切勿將原始的
error.message暴露給 UI;僅顯示本地化字串。 - 除非明確要求,否則不要新增額外語言。
- 偏好結構化命名空間(例如
errors.*、buttons.*、workspace.*)。 - 保持翻譯簡潔一致。
- 某些技術/品牌術語應保持不翻譯(例如產品名稱、API、MCP、Bash)。
交付產出(預期輸出)
- i18n 設定/Provider 接線。
- 每個目標語言的語言檔。
- 已取代為穩定金鑰的 UI 字串。
- 語言切換器與持久化機制(若適用)。
- 針對可見文字更新後的測試。
架構指引(保持簡潔)
- 金鑰結構:偏好按區域巢狀組織命名空間(例如
common.buttons.save、pricing.tier.pro)。 - 檔案佈局:每個語言一個檔案,或每個命名空間一個語言檔;保持不同語言間的金鑰同步。
- 佔位符:精確保留
{name}/{{name}};依語言規則驗證複數形式。 - 格式化:對日期、時間、數字與清單格式化使用 Intl/應用程式輔助函式。
- SEO/中繼資料:若應用程式會暴露這些內容,請本地化標題與描述。
- RTL:僅在 RTL 語言時需要;使用邏輯 CSS 屬性並測試版面。
- 非 Web 表面(Electron 主處理程序對話框、CLI 提示、原生選單)也需要本地化。
效能備註(簡短)
- 當應用程式支援時,對語言套件進行惰性載入。
- 依命名空間拆分大型語言檔。
失敗模式(監控清單)
- 缺少翻譯:回退到預設語言並記錄警告。
- RTL 版面問題:驗證邏輯 CSS 並測試頁面。
- SEO 遺漏:確保適用時本地化替代網址與中繼資料。
驗證檢查清單(簡短)
- 無缺少金鑰且無原始 UI 字串。
- 語言切換正常運作並持久化。
- 在兩種語言中驗證複數規則與格式化。
- 已設定後備語言。
資源
scripts/
scripts/i18n_audit.py:擷取t('key')的使用情況並與語言 JSON 檔案進行比較。
觸發條件
將錯誤碼映射到本地化訊息,以及驗證金鑰對等性、複數規則與格式化。