戰(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 條目并針對(duì)阿拉伯語、波斯語、希伯來語、烏爾都語提供 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)先級(jí)為 cookie →x-locale請(qǐng)求頭 → 默認(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()把英文源作為缺失鍵的兜底隨后再做一次命名空間級(jí)淺合并保證新增命名空間如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)先級(jí)來源示例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)分隔、相對(duì)倉庫根的路徑 npm run i18n:run -- --filesCLAUDE.md,docs/architecture/ARCHITECTURE.md # 強(qiáng)制全量重譯成本高 npm run i18n:run -- --force # 預(yù)演——不發(fā) API 請(qǐng)求、不寫任何文件 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對(duì)應(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表示只對(duì)磁盤上的鏡像重新哈希、保留全部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對(duì)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__連接多條字符串單請(qǐng)求上限 1800 字符最小化 API 調(diào)用次數(shù)內(nèi)存緩存會(huì)話內(nèi)相同字符串不重復(fù)調(diào)用指數(shù)退避重試429/5xx 最多重試 5 次延遲為 300ms × 嘗試次數(shù)超時(shí)單請(qǐng)求 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對(duì)比并報(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 對(duì)儀表盤所有路由在多種 locale 與多種視口下截圖并評(píng)估頁面健康度# 默認(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è)——對(duì)矩陣中的每個(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 腳本一一對(duì)應(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ì)顯示來自u(píng)ntranslatable-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 鍵量級(jí) ├── 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ù)用?！久赓M(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 條目并針對(duì)阿拉伯語、波斯語、希伯來語、烏爾都語提供 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)先級(jí)為 cookie →x-locale請(qǐng)求頭 → 默認(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()把英文源作為缺失鍵的兜底隨后再做一次命名空間級(jí)淺合并保證新增命名空間如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)先級(jí)來源示例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)分隔、相對(duì)倉庫根的路徑 npm run i18n:run -- --filesCLAUDE.md,docs/architecture/ARCHITECTURE.md # 強(qiáng)制全量重譯成本高 npm run i18n:run -- --force # 預(yù)演——不發(fā) API 請(qǐng)求、不寫任何文件 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對(duì)應(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表示只對(duì)磁盤上的鏡像重新哈希、保留全部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對(duì)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__連接多條字符串單請(qǐng)求上限 1800 字符最小化 API 調(diào)用次數(shù)內(nèi)存緩存會(huì)話內(nèi)相同字符串不重復(fù)調(diào)用指數(shù)退避重試429/5xx 最多重試 5 次延遲為 300ms × 嘗試次數(shù)超時(shí)單請(qǐng)求 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對(duì)比并報(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 對(duì)儀表盤所有路由在多種 locale 與多種視口下截圖并評(píng)估頁面健康度# 默認(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è)——對(duì)矩陣中的每個(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 腳本一一對(duì)應(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ì)顯示來自u(píng)ntranslatable-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 鍵量級(jí) ├── 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ù)用?！久赓M(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），僅供參考