戰(zhàn)指南：42 語言、增量翻譯流水線與全鏈路質(zhì)量門禁)
OmniRoute i18n 國際化工程實(shí)戰(zhàn)指南42 語言、增量翻譯流水線與全鏈路質(zhì)量門禁【免費(fèi)下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute導(dǎo)讀OmniRoute 是一個(gè)面向 AI 網(wǎng)關(guān)場景的開源項(xiàng)目其國際化體系覆蓋了儀表盤 UI、命令行CLI、項(xiàng)目文檔三大表面當(dāng)前倉庫中共配置了 42 個(gè)語言環(huán)境config/i18n.json中可見 42 個(gè) locale 條目并針對阿拉伯語、波斯語、希伯來語、烏爾都語提供 RTL 支持。本篇指南以倉庫自帶的 i18n 工程文檔docs/i18n/fi/docs/guides/I18N.md 及其英文主文檔 docs/guides/I18N.md為核心骨架結(jié)合 scripts/i18n 目錄下的真實(shí)腳本與 src/i18n 的運(yùn)行時(shí)實(shí)現(xiàn)系統(tǒng)講解其架構(gòu)、增量翻譯流水線、新增語言流程、驗(yàn)證與 QA 工具鏈。讀完本文你將掌握如何為 OmniRoute 添加一種新語言、如何驅(qū)動(dòng)哈希增量翻譯、如何用校驗(yàn)?zāi)_本守住翻譯質(zhì)量以及如何將 i18n 檢查接入 CI。說明FinnishSuomifi版本是英文原版 I18N 指南的翻譯鏡像之一下文以內(nèi)容更全的英文主文檔為準(zhǔn)并結(jié)合fi版中保留的 Quick Reference、架構(gòu)、驗(yàn)證命令等核心內(nèi)容。一、i18n 架構(gòu)總覽三層表面與單一事實(shí)來源OmniRoute 的國際化并不是一套字典走天下而是三個(gè)各自獨(dú)立、又共享同一份 locale 清單的子系統(tǒng)表面承載文件說明儀表盤 UINext.jssrc/i18n/messages/{locale}.json約 2800 個(gè)鍵的英文源en.json加 41 個(gè)翻譯文件命令行 CLIbin/cli/locales/{locale}.json42 個(gè)開箱即用的 CLI 語言目錄文檔 Docsdocs/i18n/{locale}/docs/...每個(gè) locale 一套翻譯后的 Markdown 鏡像單一事實(shí)來源是 config/i18n.json。該文件聲明了defaulten、rtl[ar,fa,he,ur]、uiOnly[en]、docsExcluded[en]以及完整的locales數(shù)組。每個(gè) locale 條目形如{ code: fi, label: FI, name: Suomi, native: Suomi, english: Finnish, flag: }注意 src/i18n/config.ts 文件頭部明確寫著SOURCE OF TRUTH: config/i18n.json… Keep this file as a thin typed adapter — do NOT add hand-maintained locale lists here.也就是說src/i18n/config.ts只是一個(gè)瘦適配層它通過 JSON import 讀取config/i18n.json再導(dǎo)出LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES、LOCALE_COOKIE等常量供 UI 使用。從源碼結(jié)構(gòu)看新增語言唯一需要手改的聲明位置就是config/i18n.json其余表面都由腳本驅(qū)動(dòng)。1.1 儀表盤 UI 的運(yùn)行時(shí)語言解析流程翻譯文檔中給出了儀表盤的 4 步運(yùn)行時(shí)流程而 src/i18n/request.ts 給出了完整實(shí)現(xiàn)用戶在界面選擇語言 → 寫入NEXT_LOCALEcookie由LOCALE_COOKIE NEXT_LOCALE定義request.ts通過resolveRequestedLocale()解析 locale優(yōu)先級為 cookie →x-locale請求頭 → 默認(rèn)en動(dòng)態(tài) import 加載messages/{locale}.json組件通過useTranslations(namespace)t(key)取字符串。實(shí)現(xiàn)層面有兩個(gè)值得注意的細(xì)節(jié)EN 兜底合并當(dāng)激活 locale 不是en時(shí)request.ts會(huì)先做一次遞歸的deepMergeFallback()把英文源作為缺失鍵的兜底隨后再做一次命名空間級淺合并保證新增命名空間如cliCode、cliAgents、acpAgents在尚未翻譯的 39 個(gè)非 EN/非 pt-BR locale 中能以英文顯示。__MISSING__:哨兵值sync-ui-keys.mjs回填未翻譯鍵時(shí)寫入__MISSING__:english value見 request.ts 中PLACEHOLDER_PREFIX的定義deepMergeFallback會(huì)把這類值當(dāng)作缺失處理從而讓干凈的英文值勝出。原型污染防護(hù)deepMergeFallback與setNestedValue都會(huì)跳過__proto__、constructor、prototype鍵防止由構(gòu)造的 locale 消息樹引發(fā)原型污染。resolveRequestedLocale()還會(huì)消費(fèi)LOCALE_ALIASES——例如舊值in曾被錯(cuò)誤地用作印地語/印尼語代碼如今通過 alias 映射到id因此用戶保存的NEXT_LOCALEin或OMNIROUTE_LANGin仍能正確解析。1.2 CLI 層的 i18n獨(dú)立于儀表盤CLI 有自己獨(dú)立的 i18n 層源文件為bin/cli/i18n.mjs所有面向用戶的字符串都經(jīng)過t(module.key, vars)目錄文件位于 bin/cli/locales42 個(gè)開箱即用任何缺失鍵回退到en因此部分翻譯的 locale 也是合法的locale 來源清單同樣共享config/i18n.json。CLI 的 locale 選擇順序首個(gè)命中優(yōu)先優(yōu)先級來源示例1--lang參數(shù)omniroute --lang de status2OMNIROUTE_LANG環(huán)境變量OMNIROUTE_LANGja omniroute providers3LC_ALL系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測4LC_MESSAGES系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測5LANG系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測6兜底en帶下劃線的代碼pt_BR會(huì)被歸一化為連字符形式pt-BRlocale 代碼必須匹配/^[a-zA-Z0-9-]$/以此拒絕路徑穿越攻擊。語言偏好可通過以下命令持久化到~/.omniroute/.env原子寫入在 CLI 引導(dǎo)階段加載# 設(shè)置語言并持久化跨會(huì)話生效 omniroute config lang set pt-BR # 查看當(dāng)前語言 omniroute config lang get # 列出全部 42 種可用語言 omniroute config lang list # JSON 輸出 omniroute config lang list --output json # 僅本次調(diào)用生效不寫入配置文件 omniroute --lang de providers list從倉庫現(xiàn)狀看42 個(gè) CLI locale 文件中en、pt-BR為完整翻譯bn、gu、he、mr、ms、phi、sw、ta、te、ur為純腳手架所有鍵回退到en其余 30 個(gè) locale 翻譯了commonprogram兩組鍵。二、翻譯流水線從 Google 免費(fèi) API 到哈希增量 LLM 翻譯2.1 推薦流水線v3.8.0 起哈希增量翻譯器當(dāng)前推薦的主流水線是 scripts/i18n/run-translation.mjs由 npm 腳本驅(qū)動(dòng)。它基于 OpenAI 兼容的 LLM 端點(diǎn)典型場景是經(jīng) OmniRoute Cloud 走cx/gpt-5.4-mini一類模型其核心特性是增量與確定性# 運(yùn)行翻譯增量——只處理源文件有變化的文檔 npm run i18n:run # 只處理一個(gè) locale npm run i18n:run -- --localept-BR # 只處理指定文件逗號(hào)分隔、相對倉庫根的路徑 npm run i18n:run -- --filesCLAUDE.md,docs/architecture/ARCHITECTURE.md # 強(qiáng)制全量重譯成本高 npm run i18n:run -- --force # 預(yù)演——不發(fā) API 請求、不寫任何文件 npm run i18n:run:dry # CI 門禁——狀態(tài)漂移時(shí)以非零碼退出 npm run i18n:check狀態(tài)文件是提交進(jìn)倉庫的 .i18n-state.json為每個(gè)源文件和每個(gè)已產(chǎn)出的目標(biāo)文件保存 SHA-256 哈希。重跑時(shí)只重譯源哈希變化了或目標(biāo)文件缺失的文件因此i18n:check對應(yīng) scripts/i18n/check-translation-drift.mjs做漂移檢測時(shí)完全不需要調(diào)用 API確定性且廉價(jià)。狀態(tài)重引導(dǎo)--adopt如果.i18n-state.json丟失或你只改了鏈接列表、數(shù)字這類無需重譯的文本可以運(yùn)行npm run i18n:run -- --adopt # 從磁盤上的鏡像重建狀態(tài)不發(fā) API、不寫任何 .md npm run i18n:run -- --adopt --targets-only--targets-only表示只對磁盤上的鏡像重新哈希、保留全部source_hash這樣機(jī)械性的鏡像重寫不會(huì)表現(xiàn)為target changed而真正的源漂移仍會(huì)被報(bào)告。從 run-translation.mjs 的注釋看--adopt與--targets-only正是為這兩類場景設(shè)計(jì)的。后端配置通過.env配置永不提交變量用途OMNIROUTE_TRANSLATION_API_URLOpenAI 兼容的 base URL如…/v1OMNIROUTE_TRANSLATION_API_KEYbearer token日志中脫敏OMNIROUTE_TRANSLATION_MODEL模型 id如cx/gpt-5.4-miniOMNIROUTE_TRANSLATION_TIMEOUT_MS可選默認(rèn)60000OMNIROUTE_TRANSLATION_CONCURRENCY可選默認(rèn)4run-translation.mjs自帶一個(gè)極簡的.env加載器不引入 dotenv 依賴已設(shè)置的環(huán)境變量優(yōu)先因此 shell / CI 仍可覆蓋。輸出形狀每份翻譯文件頂部是# heading (native)行、一條 Languages: …語言欄、一個(gè)---分隔符然后才是翻譯正文。這一版式與scripts/check/check-docs-sync.mjs對llm.txt、CHANGELOG.md鏡像的既有約束保持一致翻譯文件在記錄哈希前還會(huì)經(jīng)過 Prettiermarkdown parser格式化避免 lint-staged 的 Prettier 二次格式化與狀態(tài)文件打架。2.2 舊流水線已棄用v3.10 移除文檔中明確標(biāo)注了兩條舊流水線為deprecated將在 v3.10 移除Google 免費(fèi) API 生成器scripts/i18n/generate-multilang.mjs約 888 行LLM 文檔翻譯器scripts/i18n/i18n_autotranslate.py。舊生成器的四個(gè)模式與行為當(dāng)前仍存在于倉庫但不應(yīng)再用于 UI 字符串node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]模式行為messages從en.json補(bǔ)齊src/i18n/messages/{locale}.json的缺失鍵readme把根目錄README.md翻譯為各語言的README.{code}.mddocs把DOC_SOURCE_FILES翻譯到docs/i18n/{locale}/{docName}all依次執(zhí)行以上三種舊生成器的工程細(xì)節(jié)仍值得了解體現(xiàn)了翻譯流水線的通用設(shè)計(jì)文本保護(hù)翻譯前先掩碼代碼塊、行內(nèi)代碼、Markdown 鏈接/圖片、HTML 標(biāo)簽、表格與 ICU 占位符{count}、{value}、{total}等翻譯后再還原分塊批處理用__OMNIROUTE_I18N_SEPARATOR__連接多條字符串單請求上限 1800 字符最小化 API 調(diào)用次數(shù)內(nèi)存緩存會(huì)話內(nèi)相同字符串不重復(fù)調(diào)用指數(shù)退避重試429/5xx 最多重試 5 次延遲為 300ms × 嘗試次數(shù)超時(shí)單請求 20 秒跳過已存在文件目標(biāo)文件已存在則不覆蓋。支持 UI 字符串翻譯的受支持路徑是 LLM 后端# 補(bǔ)齊每個(gè) locale 目錄中缺失/占位的 UI 鍵 npm run i18n:sync-ui -- --translate-markers --batch-size40根目錄README.{code}.md變體目前尚無替代流水線readme模式是唯一的例外。三、新增一種語言一條命令鋪平所有表面老版本文檔要求手動(dòng)編輯generate-multilang.mjs的LOCALE_SPECS數(shù)組fi版芬蘭語文檔仍保留這一舊流程而英文主文檔與當(dāng)前倉庫已演進(jìn)為add-locale.mjs單命令流程——從 scripts/i18n/add-locale.mjs 的實(shí)現(xiàn)看它會(huì)一次性把新 locale 寫入config/i18n.json、旗幟文件docs/assets/flags/cc.svg、UI 目錄src/i18n/messages/code.json腳手架后經(jīng)sync-ui-keys --translate-markers填充、文檔鏡像docs/i18n/code/**、CLI 目錄bin/cli/locales/code.json、README 旗幟鏈接、docs/i18n/README.md行、docs/guides/I18N.md行以及可選的 site 目錄。# 需要 .env 中配置 OMNIROUTE_TRANSLATION_API_URL / _API_KEY / _MODEL node scripts/i18n/add-locale.mjs --codeel --englishGreek --nativeΕλληνικ? --flag # 印度語系共用 in.svg 旗幟文件 node scripts/i18n/add-locale.mjs --codekn --englishKannada --native????? --flag --flag-filein.svg # 只預(yù)覽不執(zhí)行 node scripts/i18n/add-locale.mjs --codeel --englishGreek --nativeΕλληνικ? --flag --dry-runadd-locale.mjs還支持--aliases、--rtl、--docscore|all、--filescsv、--cli-full等可選參數(shù)。新增后執(zhí)行驗(yàn)證node --import tsx/esm --test tests/unit/i18n-locale-surfaces-parity.test.ts npm run i18n:check-ui-coverage npm run i18n:check-ratio npm run check:docs-all npm run check:cli-i18n其中tests/unit/i18n-locale-surfaces-parity.test.ts雙向守護(hù)配置的文檔 locale 必須有一行記錄且每行記錄必須映射回一個(gè)已配置的文檔 locale。核心原則再次重申config/i18n.json是聲明新語言的唯一位置src/i18n/config.ts是類型化適配層禁止手改。四、驗(yàn)證與 QA 工具鏈四層檢查保住翻譯質(zhì)量4.1 翻譯校驗(yàn)器 validate_translation.pyscripts/i18n/validate_translation.py 將任意 locale JSON 與en.json對比并報(bào)告問題# 快速檢查僅計(jì)數(shù) python3 scripts/i18n/validate_translation.py quick -l cs # 輸出示例 # Missing: 0 # Untranslated: 0 # Ignored (UNTRANSLATABLE_KEYS): 236 # 按分類輸出差異 python3 scripts/i18n/validate_translation.py diff common -l cs python3 scripts/i18n/validate_translation.py diff settings -l cs # 導(dǎo)出 CSV / Markdown python3 scripts/i18n/validate_translation.py csv -l cs report.csv python3 scripts/i18n/validate_translation.py md -l cs report.md # 完整報(bào)告默認(rèn) python3 scripts/i18n/validate_translation.py -l cs檢測四類問題Missing keys——en.json有、locale 文件沒有的鍵Extra keys——locale 文件有、en.json沒有的鍵Untranslated keys——locale 值與英文源相同的鍵排除 allowlistPlaceholder mismatches——ICU 占位符在源與譯文間不匹配。退出碼約定碼含義0OK1一般錯(cuò)誤2缺少字符串硬錯(cuò)誤3未翻譯警告軟錯(cuò)誤環(huán)境變量可用TRANSLATION_LANGcs或-l cs參數(shù)二選一。4.2 代碼鍵檢查器 check_translations.pyscripts/i18n/check_translations.py 掃描src/**/*.tsx與src/**/*.ts中的useTranslations()調(diào)用驗(yàn)證所有被引用的鍵都存在于en.json# 基礎(chǔ)檢查 python3 scripts/i18n/check_translations.py # 詳細(xì)輸出 python3 scripts/i18n/check_translations.py --verbose # 自動(dòng)修復(fù)把缺失鍵補(bǔ)進(jìn) en.json python3 scripts/i18n/check_translations.py --fix4.3 靜態(tài) QA 報(bào)告 generate-qa-checklist.mjsscripts/i18n/generate-qa-checklist.mjs 掃描 Next.js 頁面文件輸出 i18n 風(fēng)險(xiǎn)指標(biāo) Markdown 報(bào)告node scripts/i18n/generate-qa-checklist.mjs檢查項(xiàng)包括固定寬度 class 的使用溢出風(fēng)險(xiǎn)、方向性 left/right classRTL 風(fēng)險(xiǎn)、易裁剪clipping模式、與en.json相比的 locale 奇偶性缺失/多余鍵、以及es/fr/de/ja/ar等優(yōu)先 locale 的 README 語言選擇欄。輸出為docs/reports/i18n-qa-checklist-{date}.md該目錄當(dāng)前未隨倉庫提交由腳本運(yùn)行時(shí)生成。4.4 視覺 QA run-visual-qa.mjsPlaywrightscripts/i18n/run-visual-qa.mjs 通過 Playwright 對儀表盤所有路由在多種 locale 與多種視口下截圖并評估頁面健康度# 默認(rèn)es, fr, de, ja, ar, zh-CN目標(biāo) localhost:20128 node scripts/i18n/run-visual-qa.mjs # 自定義 base URL 與 locale QA_BASE_URLhttp://staging.example.com QA_LOCALESde,fr node scripts/i18n/run-visual-qa.mjs # 自定義路由 QA_ROUTES/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs可檢測文本溢出、元素裁剪、RTL 布局錯(cuò)位。輸出docs/reports/i18n-visual-qa-{date}.md加 JSON 報(bào)告。4.5 術(shù)語一致性層glossary超出鍵奇偶與 ICU 合法性的第三道門禁僅靠鍵奇偶check-ui-keys-coverage.mjs和 ICU 合法性validate_translation.py無法發(fā)現(xiàn)語義漂移——例如同一個(gè)英文概念 provider 在中文里同時(shí)被譯為提供商與提供者。為此倉庫新增了術(shù)語表層文檔注明由 #8038 引入從 zh-CN 起步scripts/i18n/glossary/zh-CN.json版本化的常見概念術(shù)語表provider、connection、routing、fallback、quota、context window、reasoning、tool call、cache、circuit breaker 等每個(gè)概念含canonical翻譯與可選的synonyms列表——目錄中出現(xiàn)任一同義詞即標(biāo)記為漂移scripts/i18n/glossary/protected-terms.json產(chǎn)品/提供商/模型/協(xié)議/CLI/環(huán)境變量/標(biāo)識(shí)符名單OmniRoute、OAuth、MCP、A2A、DATA_DIR等必須逐字出現(xiàn)在任何翻譯值中。它與untranslatable-keys.json粒度不同后者按整個(gè)鍵排除前者按概念檢查任意值中出現(xiàn)的受保護(hù)詞scripts/i18n/check-glossary-consistency.mjs導(dǎo)出純函數(shù)checkGlossaryConsistency(localeMessages, glossary, protectedTerms)返回{ violations: [...] }——非規(guī)范詞產(chǎn)生glossary-synonym違規(guī)受保護(hù)名被譯錯(cuò)產(chǎn)生protected-term-altered違規(guī)。# 默認(rèn)檢查 zh-CN npm run i18n:check-glossary # 指定 locale、JSON 報(bào)告或非失敗報(bào)告模式 node scripts/i18n/check-glossary-consistency.mjs --localezh-CN node scripts/i18n/check-glossary-consistency.mjs --localezh-CN --json node scripts/i18n/check-glossary-consistency.mjs --localezh-CN --report該檢查在 CI 中作為i18n-glossary-zhcn作業(yè)運(yùn)行與i18n-ui-coverage相同的門禁策略跳過 draft PRi18n 或代碼變更時(shí)觸發(fā)。倉庫同時(shí)提供了 scripts/i18n/glossary/ko.json、scripts/i18n/glossary/zh-TW.json 與glossary-normalize.mjsrun-translation.mjs會(huì)調(diào)用它做翻譯后術(shù)語歸一化說明該層正在向更多語言擴(kuò)展。五、不可翻譯鍵白名單與手工編輯注意點(diǎn)scripts/i18n/untranslatable-keys.json 是應(yīng)保持與英文源完全一致的鍵白名單用于避免validate_translation.py產(chǎn)生誤報(bào)的 untranslated 警告。典型成員品牌/產(chǎn)品名landing.brandName、common.social-github技術(shù)術(shù)語/縮寫health.cpu、mcpDashboard.pid、settings.aiICU/格式化字符串a(chǎn)piManager.modelsCount、health.millisecondsShort占位符值providers.openaiBaseUrlPlaceholder、cliTools.baseUrlPlaceholder協(xié)議名common.http、common.oauth、providers.oauth2Label導(dǎo)航分組sidebar.primarySection、sidebar.cliSection添加鍵只需編輯keys數(shù)組后重跑校驗(yàn)。文檔還特別提醒docs/i18n/README.md已不再由腳本整體重生成而是由i18n:add-locale就地插入新 locale 行并手工維護(hù)其余編輯——任何手工編輯若想保留應(yīng)寫入docs/guides/I18N.md這類手寫文檔而不是自動(dòng)生成的索引。六、CI 集成全 locale 并行校驗(yàn).github/workflows/ci.yml 在每次 push 與 PR 上并行校驗(yàn)所有 localei18n-matrix作業(yè)——?jiǎng)討B(tài)發(fā)現(xiàn)全部 locale 文件排除en.jsoni18n作業(yè)——對矩陣中的每個(gè) locale 并行運(yùn)行validate_translation.py quick -l langci-summary作業(yè)——匯總結(jié)果到儀表盤。# i18n-matrix: 發(fā)現(xiàn)語言 LANGS$(ls src/i18n/messages/*.json | xargs -n1 basename | sed s/.json$// | grep -v ^en$) # i18n: 校驗(yàn)每種語言 python3 scripts/i18n/validate_translation.py quick -l ${{ matrix.lang }}儀表盤輸出形如## Translations | Metric | Value | |--------|------| | Languages checked | 30 | | Total untranslated | 0 | ? All translations complete此外CI 還掛載了i18n-check漂移門禁、i18n-ui-coverageUI 鍵覆蓋與i18n-glossary-zhcn術(shù)語一致性等作業(yè)與 package.json 中i18n:*系列 npm 腳本一一對應(yīng)npm 腳本底層腳本作用i18n:run/i18n:run:dryrun-translation.mjs增量文檔翻譯 / 預(yù)演i18n:checkcheck-translation-drift.mjs漂移檢測無 API 調(diào)用i18n:sync-uisync-ui-keys.mjs補(bǔ)齊 UI 目錄缺失鍵i18n:check-ui-coveragecheck-ui-keys-coverage.mjsUI 鍵覆蓋檢查i18n:check-ratiocheck-translation-ratio.mjs真實(shí)翻譯比例棘輪與英文相同/占位符占比i18n:sync-barssync-language-bars.mjs重生成 語言欄i18n:add-localeadd-locale.mjs全表面新增語言i18n:check-glossarycheck-glossary-consistency.mjs術(shù)語一致性檢查七、最佳實(shí)踐與歷史教訓(xùn)7.1 編輯翻譯時(shí)的操作紀(jì)律永遠(yuǎn)先改en.json——它是事實(shí)來源運(yùn)行npm run i18n:sync-ui -- --translate-markers舊流程為generate-multilang.mjs messages把新鍵傳播到各 locale人工復(fù)核自動(dòng)翻譯——機(jī)器翻譯只是起點(diǎn)提交前校驗(yàn)——python3 scripts/i18n/validate_translation.py quick -l lang若某鍵應(yīng)保持英文更新untranslatable-keys.json。7.2 占位符安全I(xiàn)CU 占位符{count}、{value}、{total}、{seconds}必須逐字保留復(fù)數(shù)格式{count, plural, one {# model} other {# models}}必須保持結(jié)構(gòu)完整校驗(yàn)器會(huì)自動(dòng)檢測占位符不匹配。7.3 代碼中新增翻譯鍵// 使用命名空間鍵 const t useTranslations(settings); t(cacheSettings); // 映射到 JSON 中的 settings.cacheSettings // 運(yùn)行 check_translations.py 驗(yàn)證鍵存在 python3 scripts/i18n/check_translations.py --verbose7.4 RTL 注意事項(xiàng)ar、fa、he、ur是 RTL localeconfig/i18n.json的rtl數(shù)組當(dāng)前版本較舊文檔又新增了fa與ur兩項(xiàng)避免硬編碼left/rightCSS改用start/end邏輯屬性run-visual-qa.mjs的視覺 QA 負(fù)責(zé)捕獲 RTL 布局錯(cuò)位。7.5 歷史教訓(xùn)已知問題in.json→hi.json修復(fù)生成器曾用已棄用的 Google 翻譯代碼in表示印地語正確應(yīng)為 ISO 639-1 的hi產(chǎn)生了一個(gè)孤兒in.json。修復(fù)方式是改代碼并刪除孤兒文件2026-09-02 又移除了作為第二印尼語存活下來的in現(xiàn)在id聲明aliases: [in]舊值自動(dòng)解析到iddocs/i18n/README.md自動(dòng)生成史該文件曾由generate-multilang.mjs docs整體重生成現(xiàn)改為add-locale就地插入行 手工維護(hù)并由i18n-locale-surfaces-parity.test.ts雙向守護(hù)白名單外部化untranslatable-keys.json從validate_translation.py內(nèi)聯(lián)的 Python set 移出為獨(dú)立 JSON 文件校驗(yàn)器運(yùn)行時(shí)加載quick輸出新增 Ignored 計(jì)數(shù)快速檢查現(xiàn)在會(huì)顯示來自untranslatable-keys.json的被忽略鍵數(shù)量Ignored (UNTRANSLATABLE_KEYS): per release。八、文件結(jié)構(gòu)速查config/ └── i18n.json # 單一事實(shí)來源42 locale、RTL 集合、uiOnly/docsExcluded src/i18n/ ├── config.ts # 類型化適配層讀取 config/i18n.json禁止手改 ├── request.ts # 運(yùn)行時(shí) locale 解析 EN 兜底合并 原型污染防護(hù) ├── detectBrowserLocale.ts # 瀏覽器 locale 探測 ├── resolveRequestedLocale.ts # cookie/header 解析與 alias 映射 └── messages/ ├── en.json # 事實(shí)來源約 2800 鍵 ├── cs.json / de.json / … # 41 個(gè)翻譯文件合計(jì) 42 bin/cli/ ├── i18n.mjs # CLI 的 t(module.key, vars) └── locales/ # 42 個(gè) CLI locale 文件 scripts/i18n/ ├── run-translation.mjs # 推薦哈希增量文檔翻譯 ├── check-translation-drift.mjs # i18n:check 漂移門禁 ├── sync-ui-keys.mjs # UI 鍵補(bǔ)齊__MISSING__: 哨兵 ├── check-ui-keys-coverage.mjs # UI 鍵覆蓋檢查 ├── check-translation-ratio.mjs # 真實(shí)翻譯比例棘輪 ├── add-locale.mjs # 全表面新增語言 ├── sync-language-bars.mjs # 語言欄同步 ├── generate-multilang.mjs # 舊 Google 翻譯生成器deprecatedv3.10 移除 ├── i18n_autotranslate.py # 舊 LLM 翻譯器deprecatedv3.10 移除 ├── validate_translation.py # 翻譯校驗(yàn)器 ├── check_translations.py # 代碼鍵檢查器 ├── generate-qa-checklist.mjs # 靜態(tài) QA 報(bào)告 ├── run-visual-qa.mjs # Playwright 視覺 QA ├── check-glossary-consistency.mjs # 術(shù)語一致性 ├── untranslatable-keys.json # 不可翻譯鍵白名單236 鍵量級 ├── glossary/ # 各語言術(shù)語表 protected-terms.json └── lib/ # docs-core-set / language-bar / translation-state 等 docs/ ├── guides/I18N.md # 手寫 i18n 工程文檔本主題主文檔 ├── i18n/README.md # 自動(dòng)維護(hù)的語言索引 ├── i18n/{locale}/docs/... # 42 個(gè)語言鏡像fi 版即其中之一 └── diagrams/i18n-flow.mmd # 流水線架構(gòu)圖源文件 └── exported/i18n-flow.svg # 導(dǎo)出的架構(gòu)圖結(jié)語OmniRoute 的國際化工程是聲明一次、處處生效的典型實(shí)踐config/i18n.json是唯一事實(shí)來源add-locale.mjs一鍵把新語言鋪到 UI、CLI、文檔與站點(diǎn)表面哈希增量流水線讓文檔翻譯變成確定性的增量任務(wù)而validate_translation.py、check_translations.py、術(shù)語表與 Playwright 視覺 QA 構(gòu)成從鍵奇偶到語義一致性的完整質(zhì)量門禁。無論你是要為本倉庫新增語言、修復(fù)翻譯漂移還是把類似的 i18n 工程思路遷移到自己的項(xiàng)目這套單一來源 腳本驅(qū)動(dòng) 四層校驗(yàn)的組合都值得直接復(fù)用。【免費(fèi)下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 OmniRoute i18n 國際化工程實(shí)戰(zhàn)指南：42 語言、增量翻譯流水線與全鏈路質(zhì)量門禁
OmniRoute i18n 國際化工程實(shí)戰(zhàn)指南42 語言、增量翻譯流水線與全鏈路質(zhì)量門禁【免費(fèi)下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute導(dǎo)讀OmniRoute 是一個(gè)面向 AI 網(wǎng)關(guān)場景的開源項(xiàng)目其國際化體系覆蓋了儀表盤 UI、命令行CLI、項(xiàng)目文檔三大表面當(dāng)前倉庫中共配置了 42 個(gè)語言環(huán)境config/i18n.json中可見 42 個(gè) locale 條目并針對阿拉伯語、波斯語、希伯來語、烏爾都語提供 RTL 支持。本篇指南以倉庫自帶的 i18n 工程文檔docs/i18n/fi/docs/guides/I18N.md 及其英文主文檔 docs/guides/I18N.md為核心骨架結(jié)合 scripts/i18n 目錄下的真實(shí)腳本與 src/i18n 的運(yùn)行時(shí)實(shí)現(xiàn)系統(tǒng)講解其架構(gòu)、增量翻譯流水線、新增語言流程、驗(yàn)證與 QA 工具鏈。讀完本文你將掌握如何為 OmniRoute 添加一種新語言、如何驅(qū)動(dòng)哈希增量翻譯、如何用校驗(yàn)?zāi)_本守住翻譯質(zhì)量以及如何將 i18n 檢查接入 CI。說明FinnishSuomifi版本是英文原版 I18N 指南的翻譯鏡像之一下文以內(nèi)容更全的英文主文檔為準(zhǔn)并結(jié)合fi版中保留的 Quick Reference、架構(gòu)、驗(yàn)證命令等核心內(nèi)容。一、i18n 架構(gòu)總覽三層表面與單一事實(shí)來源OmniRoute 的國際化并不是一套字典走天下而是三個(gè)各自獨(dú)立、又共享同一份 locale 清單的子系統(tǒng)表面承載文件說明儀表盤 UINext.jssrc/i18n/messages/{locale}.json約 2800 個(gè)鍵的英文源en.json加 41 個(gè)翻譯文件命令行 CLIbin/cli/locales/{locale}.json42 個(gè)開箱即用的 CLI 語言目錄文檔 Docsdocs/i18n/{locale}/docs/...每個(gè) locale 一套翻譯后的 Markdown 鏡像單一事實(shí)來源是 config/i18n.json。該文件聲明了defaulten、rtl[ar,fa,he,ur]、uiOnly[en]、docsExcluded[en]以及完整的locales數(shù)組。每個(gè) locale 條目形如{ code: fi, label: FI, name: Suomi, native: Suomi, english: Finnish, flag: }注意 src/i18n/config.ts 文件頭部明確寫著SOURCE OF TRUTH: config/i18n.json… Keep this file as a thin typed adapter — do NOT add hand-maintained locale lists here.也就是說src/i18n/config.ts只是一個(gè)瘦適配層它通過 JSON import 讀取config/i18n.json再導(dǎo)出LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES、LOCALE_COOKIE等常量供 UI 使用。從源碼結(jié)構(gòu)看新增語言唯一需要手改的聲明位置就是config/i18n.json其余表面都由腳本驅(qū)動(dòng)。1.1 儀表盤 UI 的運(yùn)行時(shí)語言解析流程翻譯文檔中給出了儀表盤的 4 步運(yùn)行時(shí)流程而 src/i18n/request.ts 給出了完整實(shí)現(xiàn)用戶在界面選擇語言 → 寫入NEXT_LOCALEcookie由LOCALE_COOKIE NEXT_LOCALE定義request.ts通過resolveRequestedLocale()解析 locale優(yōu)先級為 cookie →x-locale請求頭 → 默認(rèn)en動(dòng)態(tài) import 加載messages/{locale}.json組件通過useTranslations(namespace)t(key)取字符串。實(shí)現(xiàn)層面有兩個(gè)值得注意的細(xì)節(jié)EN 兜底合并當(dāng)激活 locale 不是en時(shí)request.ts會(huì)先做一次遞歸的deepMergeFallback()把英文源作為缺失鍵的兜底隨后再做一次命名空間級淺合并保證新增命名空間如cliCode、cliAgents、acpAgents在尚未翻譯的 39 個(gè)非 EN/非 pt-BR locale 中能以英文顯示。__MISSING__:哨兵值sync-ui-keys.mjs回填未翻譯鍵時(shí)寫入__MISSING__:english value見 request.ts 中PLACEHOLDER_PREFIX的定義deepMergeFallback會(huì)把這類值當(dāng)作缺失處理從而讓干凈的英文值勝出。原型污染防護(hù)deepMergeFallback與setNestedValue都會(huì)跳過__proto__、constructor、prototype鍵防止由構(gòu)造的 locale 消息樹引發(fā)原型污染。resolveRequestedLocale()還會(huì)消費(fèi)LOCALE_ALIASES——例如舊值in曾被錯(cuò)誤地用作印地語/印尼語代碼如今通過 alias 映射到id因此用戶保存的NEXT_LOCALEin或OMNIROUTE_LANGin仍能正確解析。1.2 CLI 層的 i18n獨(dú)立于儀表盤CLI 有自己獨(dú)立的 i18n 層源文件為bin/cli/i18n.mjs所有面向用戶的字符串都經(jīng)過t(module.key, vars)目錄文件位于 bin/cli/locales42 個(gè)開箱即用任何缺失鍵回退到en因此部分翻譯的 locale 也是合法的locale 來源清單同樣共享config/i18n.json。CLI 的 locale 選擇順序首個(gè)命中優(yōu)先優(yōu)先級來源示例1--lang參數(shù)omniroute --lang de status2OMNIROUTE_LANG環(huán)境變量OMNIROUTE_LANGja omniroute providers3LC_ALL系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測4LC_MESSAGES系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測5LANG系統(tǒng)環(huán)境從終端 locale 自動(dòng)探測6兜底en帶下劃線的代碼pt_BR會(huì)被歸一化為連字符形式pt-BRlocale 代碼必須匹配/^[a-zA-Z0-9-]$/以此拒絕路徑穿越攻擊。語言偏好可通過以下命令持久化到~/.omniroute/.env原子寫入在 CLI 引導(dǎo)階段加載# 設(shè)置語言并持久化跨會(huì)話生效 omniroute config lang set pt-BR # 查看當(dāng)前語言 omniroute config lang get # 列出全部 42 種可用語言 omniroute config lang list # JSON 輸出 omniroute config lang list --output json # 僅本次調(diào)用生效不寫入配置文件 omniroute --lang de providers list從倉庫現(xiàn)狀看42 個(gè) CLI locale 文件中en、pt-BR為完整翻譯bn、gu、he、mr、ms、phi、sw、ta、te、ur為純腳手架所有鍵回退到en其余 30 個(gè) locale 翻譯了commonprogram兩組鍵。二、翻譯流水線從 Google 免費(fèi) API 到哈希增量 LLM 翻譯2.1 推薦流水線v3.8.0 起哈希增量翻譯器當(dāng)前推薦的主流水線是 scripts/i18n/run-translation.mjs由 npm 腳本驅(qū)動(dòng)。它基于 OpenAI 兼容的 LLM 端點(diǎn)典型場景是經(jīng) OmniRoute Cloud 走cx/gpt-5.4-mini一類模型其核心特性是增量與確定性# 運(yùn)行翻譯增量——只處理源文件有變化的文檔 npm run i18n:run # 只處理一個(gè) locale npm run i18n:run -- --localept-BR # 只處理指定文件逗號(hào)分隔、相對倉庫根的路徑 npm run i18n:run -- --filesCLAUDE.md,docs/architecture/ARCHITECTURE.md # 強(qiáng)制全量重譯成本高 npm run i18n:run -- --force # 預(yù)演——不發(fā) API 請求、不寫任何文件 npm run i18n:run:dry # CI 門禁——狀態(tài)漂移時(shí)以非零碼退出 npm run i18n:check狀態(tài)文件是提交進(jìn)倉庫的 .i18n-state.json為每個(gè)源文件和每個(gè)已產(chǎn)出的目標(biāo)文件保存 SHA-256 哈希。重跑時(shí)只重譯源哈希變化了或目標(biāo)文件缺失的文件因此i18n:check對應(yīng) scripts/i18n/check-translation-drift.mjs做漂移檢測時(shí)完全不需要調(diào)用 API確定性且廉價(jià)。狀態(tài)重引導(dǎo)--adopt如果.i18n-state.json丟失或你只改了鏈接列表、數(shù)字這類無需重譯的文本可以運(yùn)行npm run i18n:run -- --adopt # 從磁盤上的鏡像重建狀態(tài)不發(fā) API、不寫任何 .md npm run i18n:run -- --adopt --targets-only--targets-only表示只對磁盤上的鏡像重新哈希、保留全部source_hash這樣機(jī)械性的鏡像重寫不會(huì)表現(xiàn)為target changed而真正的源漂移仍會(huì)被報(bào)告。從 run-translation.mjs 的注釋看--adopt與--targets-only正是為這兩類場景設(shè)計(jì)的。后端配置通過.env配置永不提交變量用途OMNIROUTE_TRANSLATION_API_URLOpenAI 兼容的 base URL如…/v1OMNIROUTE_TRANSLATION_API_KEYbearer token日志中脫敏OMNIROUTE_TRANSLATION_MODEL模型 id如cx/gpt-5.4-miniOMNIROUTE_TRANSLATION_TIMEOUT_MS可選默認(rèn)60000OMNIROUTE_TRANSLATION_CONCURRENCY可選默認(rèn)4run-translation.mjs自帶一個(gè)極簡的.env加載器不引入 dotenv 依賴已設(shè)置的環(huán)境變量優(yōu)先因此 shell / CI 仍可覆蓋。輸出形狀每份翻譯文件頂部是# heading (native)行、一條 Languages: …語言欄、一個(gè)---分隔符然后才是翻譯正文。這一版式與scripts/check/check-docs-sync.mjs對llm.txt、CHANGELOG.md鏡像的既有約束保持一致翻譯文件在記錄哈希前還會(huì)經(jīng)過 Prettiermarkdown parser格式化避免 lint-staged 的 Prettier 二次格式化與狀態(tài)文件打架。2.2 舊流水線已棄用v3.10 移除文檔中明確標(biāo)注了兩條舊流水線為deprecated將在 v3.10 移除Google 免費(fèi) API 生成器scripts/i18n/generate-multilang.mjs約 888 行LLM 文檔翻譯器scripts/i18n/i18n_autotranslate.py。舊生成器的四個(gè)模式與行為當(dāng)前仍存在于倉庫但不應(yīng)再用于 UI 字符串node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]模式行為messages從en.json補(bǔ)齊src/i18n/messages/{locale}.json的缺失鍵readme把根目錄README.md翻譯為各語言的README.{code}.mddocs把DOC_SOURCE_FILES翻譯到docs/i18n/{locale}/{docName}all依次執(zhí)行以上三種舊生成器的工程細(xì)節(jié)仍值得了解體現(xiàn)了翻譯流水線的通用設(shè)計(jì)文本保護(hù)翻譯前先掩碼代碼塊、行內(nèi)代碼、Markdown 鏈接/圖片、HTML 標(biāo)簽、表格與 ICU 占位符{count}、{value}、{total}等翻譯后再還原分塊批處理用__OMNIROUTE_I18N_SEPARATOR__連接多條字符串單請求上限 1800 字符最小化 API 調(diào)用次數(shù)內(nèi)存緩存會(huì)話內(nèi)相同字符串不重復(fù)調(diào)用指數(shù)退避重試429/5xx 最多重試 5 次延遲為 300ms × 嘗試次數(shù)超時(shí)單請求 20 秒跳過已存在文件目標(biāo)文件已存在則不覆蓋。支持 UI 字符串翻譯的受支持路徑是 LLM 后端# 補(bǔ)齊每個(gè) locale 目錄中缺失/占位的 UI 鍵 npm run i18n:sync-ui -- --translate-markers --batch-size40根目錄README.{code}.md變體目前尚無替代流水線readme模式是唯一的例外。三、新增一種語言一條命令鋪平所有表面老版本文檔要求手動(dòng)編輯generate-multilang.mjs的LOCALE_SPECS數(shù)組fi版芬蘭語文檔仍保留這一舊流程而英文主文檔與當(dāng)前倉庫已演進(jìn)為add-locale.mjs單命令流程——從 scripts/i18n/add-locale.mjs 的實(shí)現(xiàn)看它會(huì)一次性把新 locale 寫入config/i18n.json、旗幟文件docs/assets/flags/cc.svg、UI 目錄src/i18n/messages/code.json腳手架后經(jīng)sync-ui-keys --translate-markers填充、文檔鏡像docs/i18n/code/**、CLI 目錄bin/cli/locales/code.json、README 旗幟鏈接、docs/i18n/README.md行、docs/guides/I18N.md行以及可選的 site 目錄。# 需要 .env 中配置 OMNIROUTE_TRANSLATION_API_URL / _API_KEY / _MODEL node scripts/i18n/add-locale.mjs --codeel --englishGreek --nativeΕλληνικ? --flag # 印度語系共用 in.svg 旗幟文件 node scripts/i18n/add-locale.mjs --codekn --englishKannada --native????? --flag --flag-filein.svg # 只預(yù)覽不執(zhí)行 node scripts/i18n/add-locale.mjs --codeel --englishGreek --nativeΕλληνικ? --flag --dry-runadd-locale.mjs還支持--aliases、--rtl、--docscore|all、--filescsv、--cli-full等可選參數(shù)。新增后執(zhí)行驗(yàn)證node --import tsx/esm --test tests/unit/i18n-locale-surfaces-parity.test.ts npm run i18n:check-ui-coverage npm run i18n:check-ratio npm run check:docs-all npm run check:cli-i18n其中tests/unit/i18n-locale-surfaces-parity.test.ts雙向守護(hù)配置的文檔 locale 必須有一行記錄且每行記錄必須映射回一個(gè)已配置的文檔 locale。核心原則再次重申config/i18n.json是聲明新語言的唯一位置src/i18n/config.ts是類型化適配層禁止手改。四、驗(yàn)證與 QA 工具鏈四層檢查保住翻譯質(zhì)量4.1 翻譯校驗(yàn)器 validate_translation.pyscripts/i18n/validate_translation.py 將任意 locale JSON 與en.json對比并報(bào)告問題# 快速檢查僅計(jì)數(shù) python3 scripts/i18n/validate_translation.py quick -l cs # 輸出示例 # Missing: 0 # Untranslated: 0 # Ignored (UNTRANSLATABLE_KEYS): 236 # 按分類輸出差異 python3 scripts/i18n/validate_translation.py diff common -l cs python3 scripts/i18n/validate_translation.py diff settings -l cs # 導(dǎo)出 CSV / Markdown python3 scripts/i18n/validate_translation.py csv -l cs report.csv python3 scripts/i18n/validate_translation.py md -l cs report.md # 完整報(bào)告默認(rèn) python3 scripts/i18n/validate_translation.py -l cs檢測四類問題Missing keys——en.json有、locale 文件沒有的鍵Extra keys——locale 文件有、en.json沒有的鍵Untranslated keys——locale 值與英文源相同的鍵排除 allowlistPlaceholder mismatches——ICU 占位符在源與譯文間不匹配。退出碼約定碼含義0OK1一般錯(cuò)誤2缺少字符串硬錯(cuò)誤3未翻譯警告軟錯(cuò)誤環(huán)境變量可用TRANSLATION_LANGcs或-l cs參數(shù)二選一。4.2 代碼鍵檢查器 check_translations.pyscripts/i18n/check_translations.py 掃描src/**/*.tsx與src/**/*.ts中的useTranslations()調(diào)用驗(yàn)證所有被引用的鍵都存在于en.json# 基礎(chǔ)檢查 python3 scripts/i18n/check_translations.py # 詳細(xì)輸出 python3 scripts/i18n/check_translations.py --verbose # 自動(dòng)修復(fù)把缺失鍵補(bǔ)進(jìn) en.json python3 scripts/i18n/check_translations.py --fix4.3 靜態(tài) QA 報(bào)告 generate-qa-checklist.mjsscripts/i18n/generate-qa-checklist.mjs 掃描 Next.js 頁面文件輸出 i18n 風(fēng)險(xiǎn)指標(biāo) Markdown 報(bào)告node scripts/i18n/generate-qa-checklist.mjs檢查項(xiàng)包括固定寬度 class 的使用溢出風(fēng)險(xiǎn)、方向性 left/right classRTL 風(fēng)險(xiǎn)、易裁剪clipping模式、與en.json相比的 locale 奇偶性缺失/多余鍵、以及es/fr/de/ja/ar等優(yōu)先 locale 的 README 語言選擇欄。輸出為docs/reports/i18n-qa-checklist-{date}.md該目錄當(dāng)前未隨倉庫提交由腳本運(yùn)行時(shí)生成。4.4 視覺 QA run-visual-qa.mjsPlaywrightscripts/i18n/run-visual-qa.mjs 通過 Playwright 對儀表盤所有路由在多種 locale 與多種視口下截圖并評估頁面健康度# 默認(rèn)es, fr, de, ja, ar, zh-CN目標(biāo) localhost:20128 node scripts/i18n/run-visual-qa.mjs # 自定義 base URL 與 locale QA_BASE_URLhttp://staging.example.com QA_LOCALESde,fr node scripts/i18n/run-visual-qa.mjs # 自定義路由 QA_ROUTES/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs可檢測文本溢出、元素裁剪、RTL 布局錯(cuò)位。輸出docs/reports/i18n-visual-qa-{date}.md加 JSON 報(bào)告。4.5 術(shù)語一致性層glossary超出鍵奇偶與 ICU 合法性的第三道門禁僅靠鍵奇偶check-ui-keys-coverage.mjs和 ICU 合法性validate_translation.py無法發(fā)現(xiàn)語義漂移——例如同一個(gè)英文概念 provider 在中文里同時(shí)被譯為提供商與提供者。為此倉庫新增了術(shù)語表層文檔注明由 #8038 引入從 zh-CN 起步scripts/i18n/glossary/zh-CN.json版本化的常見概念術(shù)語表provider、connection、routing、fallback、quota、context window、reasoning、tool call、cache、circuit breaker 等每個(gè)概念含canonical翻譯與可選的synonyms列表——目錄中出現(xiàn)任一同義詞即標(biāo)記為漂移scripts/i18n/glossary/protected-terms.json產(chǎn)品/提供商/模型/協(xié)議/CLI/環(huán)境變量/標(biāo)識(shí)符名單OmniRoute、OAuth、MCP、A2A、DATA_DIR等必須逐字出現(xiàn)在任何翻譯值中。它與untranslatable-keys.json粒度不同后者按整個(gè)鍵排除前者按概念檢查任意值中出現(xiàn)的受保護(hù)詞scripts/i18n/check-glossary-consistency.mjs導(dǎo)出純函數(shù)checkGlossaryConsistency(localeMessages, glossary, protectedTerms)返回{ violations: [...] }——非規(guī)范詞產(chǎn)生glossary-synonym違規(guī)受保護(hù)名被譯錯(cuò)產(chǎn)生protected-term-altered違規(guī)。# 默認(rèn)檢查 zh-CN npm run i18n:check-glossary # 指定 locale、JSON 報(bào)告或非失敗報(bào)告模式 node scripts/i18n/check-glossary-consistency.mjs --localezh-CN node scripts/i18n/check-glossary-consistency.mjs --localezh-CN --json node scripts/i18n/check-glossary-consistency.mjs --localezh-CN --report該檢查在 CI 中作為i18n-glossary-zhcn作業(yè)運(yùn)行與i18n-ui-coverage相同的門禁策略跳過 draft PRi18n 或代碼變更時(shí)觸發(fā)。倉庫同時(shí)提供了 scripts/i18n/glossary/ko.json、scripts/i18n/glossary/zh-TW.json 與glossary-normalize.mjsrun-translation.mjs會(huì)調(diào)用它做翻譯后術(shù)語歸一化說明該層正在向更多語言擴(kuò)展。五、不可翻譯鍵白名單與手工編輯注意點(diǎn)scripts/i18n/untranslatable-keys.json 是應(yīng)保持與英文源完全一致的鍵白名單用于避免validate_translation.py產(chǎn)生誤報(bào)的 untranslated 警告。典型成員品牌/產(chǎn)品名landing.brandName、common.social-github技術(shù)術(shù)語/縮寫health.cpu、mcpDashboard.pid、settings.aiICU/格式化字符串a(chǎn)piManager.modelsCount、health.millisecondsShort占位符值providers.openaiBaseUrlPlaceholder、cliTools.baseUrlPlaceholder協(xié)議名common.http、common.oauth、providers.oauth2Label導(dǎo)航分組sidebar.primarySection、sidebar.cliSection添加鍵只需編輯keys數(shù)組后重跑校驗(yàn)。文檔還特別提醒docs/i18n/README.md已不再由腳本整體重生成而是由i18n:add-locale就地插入新 locale 行并手工維護(hù)其余編輯——任何手工編輯若想保留應(yīng)寫入docs/guides/I18N.md這類手寫文檔而不是自動(dòng)生成的索引。六、CI 集成全 locale 并行校驗(yàn).github/workflows/ci.yml 在每次 push 與 PR 上并行校驗(yàn)所有 localei18n-matrix作業(yè)——?jiǎng)討B(tài)發(fā)現(xiàn)全部 locale 文件排除en.jsoni18n作業(yè)——對矩陣中的每個(gè) locale 并行運(yùn)行validate_translation.py quick -l langci-summary作業(yè)——匯總結(jié)果到儀表盤。# i18n-matrix: 發(fā)現(xiàn)語言 LANGS$(ls src/i18n/messages/*.json | xargs -n1 basename | sed s/.json$// | grep -v ^en$) # i18n: 校驗(yàn)每種語言 python3 scripts/i18n/validate_translation.py quick -l ${{ matrix.lang }}儀表盤輸出形如## Translations | Metric | Value | |--------|------| | Languages checked | 30 | | Total untranslated | 0 | ? All translations complete此外CI 還掛載了i18n-check漂移門禁、i18n-ui-coverageUI 鍵覆蓋與i18n-glossary-zhcn術(shù)語一致性等作業(yè)與 package.json 中i18n:*系列 npm 腳本一一對應(yīng)npm 腳本底層腳本作用i18n:run/i18n:run:dryrun-translation.mjs增量文檔翻譯 / 預(yù)演i18n:checkcheck-translation-drift.mjs漂移檢測無 API 調(diào)用i18n:sync-uisync-ui-keys.mjs補(bǔ)齊 UI 目錄缺失鍵i18n:check-ui-coveragecheck-ui-keys-coverage.mjsUI 鍵覆蓋檢查i18n:check-ratiocheck-translation-ratio.mjs真實(shí)翻譯比例棘輪與英文相同/占位符占比i18n:sync-barssync-language-bars.mjs重生成 語言欄i18n:add-localeadd-locale.mjs全表面新增語言i18n:check-glossarycheck-glossary-consistency.mjs術(shù)語一致性檢查七、最佳實(shí)踐與歷史教訓(xùn)7.1 編輯翻譯時(shí)的操作紀(jì)律永遠(yuǎn)先改en.json——它是事實(shí)來源運(yùn)行npm run i18n:sync-ui -- --translate-markers舊流程為generate-multilang.mjs messages把新鍵傳播到各 locale人工復(fù)核自動(dòng)翻譯——機(jī)器翻譯只是起點(diǎn)提交前校驗(yàn)——python3 scripts/i18n/validate_translation.py quick -l lang若某鍵應(yīng)保持英文更新untranslatable-keys.json。7.2 占位符安全I(xiàn)CU 占位符{count}、{value}、{total}、{seconds}必須逐字保留復(fù)數(shù)格式{count, plural, one {# model} other {# models}}必須保持結(jié)構(gòu)完整校驗(yàn)器會(huì)自動(dòng)檢測占位符不匹配。7.3 代碼中新增翻譯鍵// 使用命名空間鍵 const t useTranslations(settings); t(cacheSettings); // 映射到 JSON 中的 settings.cacheSettings // 運(yùn)行 check_translations.py 驗(yàn)證鍵存在 python3 scripts/i18n/check_translations.py --verbose7.4 RTL 注意事項(xiàng)ar、fa、he、ur是 RTL localeconfig/i18n.json的rtl數(shù)組當(dāng)前版本較舊文檔又新增了fa與ur兩項(xiàng)避免硬編碼left/rightCSS改用start/end邏輯屬性run-visual-qa.mjs的視覺 QA 負(fù)責(zé)捕獲 RTL 布局錯(cuò)位。7.5 歷史教訓(xùn)已知問題in.json→hi.json修復(fù)生成器曾用已棄用的 Google 翻譯代碼in表示印地語正確應(yīng)為 ISO 639-1 的hi產(chǎn)生了一個(gè)孤兒in.json。修復(fù)方式是改代碼并刪除孤兒文件2026-09-02 又移除了作為第二印尼語存活下來的in現(xiàn)在id聲明aliases: [in]舊值自動(dòng)解析到iddocs/i18n/README.md自動(dòng)生成史該文件曾由generate-multilang.mjs docs整體重生成現(xiàn)改為add-locale就地插入行 手工維護(hù)并由i18n-locale-surfaces-parity.test.ts雙向守護(hù)白名單外部化untranslatable-keys.json從validate_translation.py內(nèi)聯(lián)的 Python set 移出為獨(dú)立 JSON 文件校驗(yàn)器運(yùn)行時(shí)加載quick輸出新增 Ignored 計(jì)數(shù)快速檢查現(xiàn)在會(huì)顯示來自untranslatable-keys.json的被忽略鍵數(shù)量Ignored (UNTRANSLATABLE_KEYS): per release。八、文件結(jié)構(gòu)速查config/ └── i18n.json # 單一事實(shí)來源42 locale、RTL 集合、uiOnly/docsExcluded src/i18n/ ├── config.ts # 類型化適配層讀取 config/i18n.json禁止手改 ├── request.ts # 運(yùn)行時(shí) locale 解析 EN 兜底合并 原型污染防護(hù) ├── detectBrowserLocale.ts # 瀏覽器 locale 探測 ├── resolveRequestedLocale.ts # cookie/header 解析與 alias 映射 └── messages/ ├── en.json # 事實(shí)來源約 2800 鍵 ├── cs.json / de.json / … # 41 個(gè)翻譯文件合計(jì) 42 bin/cli/ ├── i18n.mjs # CLI 的 t(module.key, vars) └── locales/ # 42 個(gè) CLI locale 文件 scripts/i18n/ ├── run-translation.mjs # 推薦哈希增量文檔翻譯 ├── check-translation-drift.mjs # i18n:check 漂移門禁 ├── sync-ui-keys.mjs # UI 鍵補(bǔ)齊__MISSING__: 哨兵 ├── check-ui-keys-coverage.mjs # UI 鍵覆蓋檢查 ├── check-translation-ratio.mjs # 真實(shí)翻譯比例棘輪 ├── add-locale.mjs # 全表面新增語言 ├── sync-language-bars.mjs # 語言欄同步 ├── generate-multilang.mjs # 舊 Google 翻譯生成器deprecatedv3.10 移除 ├── i18n_autotranslate.py # 舊 LLM 翻譯器deprecatedv3.10 移除 ├── validate_translation.py # 翻譯校驗(yàn)器 ├── check_translations.py # 代碼鍵檢查器 ├── generate-qa-checklist.mjs # 靜態(tài) QA 報(bào)告 ├── run-visual-qa.mjs # Playwright 視覺 QA ├── check-glossary-consistency.mjs # 術(shù)語一致性 ├── untranslatable-keys.json # 不可翻譯鍵白名單236 鍵量級 ├── glossary/ # 各語言術(shù)語表 protected-terms.json └── lib/ # docs-core-set / language-bar / translation-state 等 docs/ ├── guides/I18N.md # 手寫 i18n 工程文檔本主題主文檔 ├── i18n/README.md # 自動(dòng)維護(hù)的語言索引 ├── i18n/{locale}/docs/... # 42 個(gè)語言鏡像fi 版即其中之一 └── diagrams/i18n-flow.mmd # 流水線架構(gòu)圖源文件 └── exported/i18n-flow.svg # 導(dǎo)出的架構(gòu)圖結(jié)語OmniRoute 的國際化工程是聲明一次、處處生效的典型實(shí)踐config/i18n.json是唯一事實(shí)來源add-locale.mjs一鍵把新語言鋪到 UI、CLI、文檔與站點(diǎn)表面哈希增量流水線讓文檔翻譯變成確定性的增量任務(wù)而validate_translation.py、check_translations.py、術(shù)語表與 Playwright 視覺 QA 構(gòu)成從鍵奇偶到語義一致性的完整質(zhì)量門禁。無論你是要為本倉庫新增語言、修復(fù)翻譯漂移還是把類似的 i18n 工程思路遷移到自己的項(xiàng)目這套單一來源 腳本驅(qū)動(dòng) 四層校驗(yàn)的組合都值得直接復(fù)用。【免費(fèi)下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors項(xiàng)目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考