OmniRoute 国际化(i18n)工具链全解析51 种语言的配置、自动翻译流水线与翻译质量验证【免费下载链接】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项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文基于 OmniRoute 仓库的国际化指南docs/guides/I18N.md多语言镜像如 docs/i18n/pt/docs/guides/I18N.md完整梳理 OmniRoute 的 i18n 体系从config/i18n.json单一事实源到next-intl运行时 locale 解析再到 Google Translate / LLM 双引擎自动翻译流水线、翻译校验器validator、静态 QA 与 Playwright 视觉 QA、以及 CI 中的翻译门禁。读完本文你可以独立完成新增一门语言、批量生成译文、修复占位符失配、让翻译校验在 CI 中保持绿灯的完整闭环。快速参考常用命令速查原文档给出的任务—命令对照表如下注意校验类脚本实际位于scripts/i18n/目录下而非文档早期版本所写的scripts/根目录任务命令生成 UI 字符串翻译Google Translatenode scripts/i18n/generate-multilang.mjs messagesLLM 翻译文档python3 scripts/i18n/i18n_autotranslate.py --api-url url --api-key key --model model校验某个语言python3 scripts/i18n/validate_translation.py quick -l cs检查代码中的键是否存在python3 scripts/i18n/check_translations.py生成静态 QA 报告node scripts/i18n/generate-qa-checklist.mjsPlaywright 视觉 QAnode scripts/i18n/run-visual-qa.mjs文档增量翻译v3.8.0 推荐管线npm run i18n:run翻译漂移 CI 门禁npm run i18n:check架构单一事实源与运行时 locale 解析单一事实源Source of TruthOmniRoute 的 i18n 数据分三层核心要点是locale 清单不再手工维护在 TS 里而是集中在一份 JSON 中locale 清单真正的事实源config/i18n.json定义default、rtl、uiOnly、docsExcluded和全部 locale 条目code/label/name/native/english/flag/ 可选aliases并受 config/i18n-schema.json 约束类型化适配器src/i18n/config.ts 以 JSON 导入import i18nConfig from ../../config/i18n.json with { type: json }的方式把该 JSON 转成LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES、LOCALE_COOKIE等常量导出见 src/i18n/config.ts文件头注释明确要求保持薄适配器不要在此添加手工维护的语言列表UI 字符串src/i18n/messages/en.json 是英文源约 2800 个键src/i18n/messages/{locale}.json为各语言译文——当前仓库中共有51 个locale JSON 文件英文源 50 个翻译框架next-intl基于 Cookie 的 locale 解析文档翻译docs/i18n/{locale}/...下按源文档布局镜像存放英文源本身不重复翻译见docsExcluded: [en]。版本说明葡萄牙语指南快照中写的是30 种语言而当前仓库英文指南 frontmatter 版本 3.8.40已扩展为51 个 UI localedocs/i18n/README.md的自述为50 种语言文档翻译 英文源UI 共支持 51 个 locale。下文以当前仓库为准。config/i18n.json中的全局字段{ default: en, rtl: [ar, fa, he, ur], uiOnly: [en], docsExcluded: [en] }rtl右起书写语言集合包含阿拉伯语、波斯语、希伯来语、乌尔都语uiOnly: [en]英文只作为 UI locale 存在本身就是源语言不需要文档翻译docsExcluded: [en]文档翻译管线跳过英文源。运行时流程Runtime Flow从请求进入页面到组件取到译文完整链路如下以 src/i18n/request.ts 为准用户在界面选择语言 → 写入NEXT_LOCALECookieLOCALE_COOKIE NEXT_LOCALE定义于 src/i18n/config.tssrc/i18n/request.ts 的getRequestConfig依次解析 localeCookie →x-locale请求头 → 兜底ensrc/i18n/request.ts。这里比旧版文档描述的Accept-Language 头更进一步文档管线与 CLI 侧也镜像了同一套解析逻辑src/i18n/resolveRequestedLocale.ts 做 locale 归一化先精确匹配再大小写不敏感匹配最后查LOCALE_ALIASES别名表例如遗留 Cookie 中的in→id、uk→uk-UA、fil/tl→phi、zh-hant→zh-TW都匹配不上则回退默认ensrc/i18n/resolveRequestedLocale.ts动态import(./messages/${locale}.json)加载该语言消息树src/i18n/request.ts双层英文兜底src/i18n/request.tsdeepMergeFallback逐键深合并en.json只补齐 locale 文件中缺失的键locale 已有值优先。同时会跳过__proto__/constructor/prototype键以防原型污染__MISSING__:哨兵i18n 同步脚本回填未翻译键时会写入__MISSING__:英文值前缀src/i18n/request.ts合并时该值被视为缺失让干净的英文兜底值生效命名空间级浅合并locale 文件中整个缺失的顶层命名空间例如新增的cliCode、acpAgents直接保留英文版本保证新命名空间在未翻译时不会报错而是显示英文组件侧使用useTranslations(namespace)t(key)取文案。受支持的 Locale当前 51 个以下表格整理自 config/i18n.jsonid行同时标注了 Google Translate 遗留代码问题见文末已知问题。RTL 语言共 4 个ar、fa、he、ur。Code语言RTLCode语言RTLarالعربية是ltLietuvių否azAzərbaycan dili否lvLatviešu否bgБългарски否mrमराठी否bnবাংলা否msBahasa Melayu否csČeština否mtMalti否daDansk否nlNederlands否deDeutsch否noNorsk否elΕλληνικά否phiFilipino否enEnglish否plPolski否esEspañol否ptPortuguês (Portugal)否etEesti否pt-BRPortuguês (Brasil)否faفارسی是roRomână否fiSuomi否ruРусский否frFrançais否skSlovenčina否gaGaeilge否slSlovenščina否guગુજરાતી否srСрпски否heעברית是svSvenska否hiहिन्दी否swKiswahili否hrHrvatski否taதமிழ்否huMagyar否teతెలుగు否idBahasa Indonesia否thไทย否itItaliano否trTürkçe否ja日本語否uk-UAУкраїнська否ko한국어否urاردو是viTiếng Việt否zh-TW中文 (繁體)否zh-CN中文 (简体)否别名aliases字段用于 Cookie/请求头归一化id ← [in]、phi ← [fil, tl]、uk-UA ← [uk]、zh-TW ← [zh-hk, zh-mo, zh-hant]。新增一门语言的完整步骤原文档给出的六步流程结合当前仓库工具链整理如下第 1、2 步现在有专用脚本1. 注册 Locale编辑 config/i18n.json在locales数组中追加条目{ code: xx, label: XX, name: Language Name, native: Language Name, english: Language Name, flag: ️ }package.json 还提供了npm run i18n:add-locale对应 scripts/i18n/add-locale.mjs作为新增 locale 的脚手架入口避免手工漏改多处文件。2. 加入翻译生成器若走 Google Translate 引擎还需在 scripts/i18n/generate-multilang.mjs 的LOCALE_SPECS数组中登记该语言code、googleTl、label、flag、languageName、readmeName、docsName。仓库中已有完整先例例如hiHindi条目为code: hi, googleTl: hiuk-UA条目为code: uk-UA, googleTl: uk——注意code是内部 locale 码googleTl才是 Google Translate 的语言码两者可以不同。3. 生成初始翻译node scripts/i18n/generate-multilang.mjs messages从en.json经 Google Translate 自动生成src/i18n/messages/xx.json。4. 人工复核自动翻译自动翻译只是起点需人工检查技术准确性、术语的上下文适配、占位符{count}、{value}等是否正确保留。5. 校验python3 scripts/i18n/validate_translation.py quick -l xx python3 scripts/i18n/validate_translation.py diff common -l xx6. 生成翻译文档旧方式为node scripts/i18n/generate-multilang.mjs docs当前推荐切换到 v3.8.0 的哈希增量 LLM 管线见下节npm run i18n:run # 增量翻译所有文档 npm run i18n:run -- --localexx # 只翻译指定语言自动翻译管线generate-multilang.mjsGoogle Translate 引擎这是主力自动翻译引擎——基于 Google Translate 免费 API为 UI 字符串src/i18n/messages/*.json与根目录 README 变体README.{code}.md生成翻译node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]模式行为messages将en.json中缺失的键翻译进src/i18n/messages/{locale}.jsonreadme将README.md翻译为根目录的README.{code}.mddocs将DOC_SOURCE_FILES翻译到docs/i18n/{locale}/{docName}all依次运行以上三种模式实现层面的关键特性均可在 scripts/i18n/generate-multilang.mjs 中核对文本保护翻译前先对代码块、行内代码、Markdown 链接/图片text、HTML 标签、表格与 ICU 占位符{count}、{value}、{total}等做掩码翻译完成后还原防止译文破坏结构分块批处理用__OMNIROUTE_I18N_SEPARATOR__分隔符把多条字符串拼进同一次 API 请求单请求上限 1800 字符大幅减少调用次数内存缓存同一会话内重复字符串不重复请求 API重试逻辑429/5xx 时指数退避重试最多 5 次延迟 300ms × 重试次数超时单请求 20 秒跳过已存在文件目标文件已存在时不覆盖messages模式只补缺失键。两个重要的运行期行为docs/i18n/README.md每次运行都会重新生成——它是全部文档的语言索引手动修改会丢失各翻译文档顶部的语言选择条 **Languages:** ...由脚本自动插入/更新另有 scripts/i18n/sync-language-bars.mjsnpm run i18n:sync-bars专门维护这些语言条。注意该脚本头部已标注DEPRECATED 2026-05-13——docs模式被新的 LLM 管线取代计划 v3.10 移除messages与readme模式目前仍由它承担。日常文档翻译请优先使用下文npm run i18n:run。i18n_autotranslate.pyLLM 引擎次级翻译器——调用任意 OpenAI 兼容 LLM API可以用 OmniRoute 自身的网关翻译docs/i18n/下已有的 Markdown 文件适合把 Google Translate 的粗译润色为更专业的技术译文python3 scripts/i18n/i18n_autotranslate.py \ --api-url http://localhost:20128/v1 \ --api-key sk-your-key \ --model gpt-4o工作方式扫描docs/i18n/中的英文段落跳过代码块、表格与已翻译内容带着技术翻译 system prompt 将段落发送给 LLM覆盖全部已配置语言。v3.8.0 哈希增量文档翻译管线当前推荐英文指南中新增、葡萄牙语快照未覆盖的部分scripts/i18n/run-translation.mjs 是基于 SHA-256 哈希的增量文档翻译器事实源为config/i18n.json 仓库内英文 MarkdownCLAUDE.md、GEMINI.md、README.md、docs/*.md等产物镜像写入docs/i18n/locale/...带 H1 头 语言条 ---分隔符。状态文件.i18n-state.json已提交进仓库记录每个源文件与每个产物目标的哈希重跑时只翻译源哈希变化或目标缺失的文件——漂移检测是自动且确定性的不需要额外 API 调用。npm run i18n:run # 增量翻译只动变化的源 npm run i18n:run -- --localept-BR # 限定一个语言 npm run i18n:run -- --filesCLAUDE.md,docs/architecture/ARCHITECTURE.md npm run i18n:run -- --force # 全量重翻费用高慎用 npm run i18n:run:dry # 预览无 API 调用、不写盘 npm run i18n:check # CI 门禁状态漂移则非零退出 npm run i18n:run -- --adopt # 从磁盘重建状态文件无 API 调用后端通过环境变量配置写入.env不提交变量作用OMNIROUTE_TRANSLATION_API_URLOpenAI 兼容 base URL如…/v1OMNIROUTE_TRANSLATION_API_KEYbearer token日志中不落盘OMNIROUTE_TRANSLATION_MODEL模型 idOMNIROUTE_TRANSLATION_TIMEOUT_MS可选默认60000OMNIROUTE_TRANSLATION_CONCURRENCY可选默认4package.json中还有一组翻译一致性检查脚本npm run前缀i18n:check漂移、i18n:sync-uisync-ui-keys.mjs即写入__MISSING__:哨兵的同步器、i18n:check-ui-coverage、i18n:check-value-drift、i18n:check-glossary术语一致性配合 scripts/i18n/glossary 与 glossary-normalize.mjs、i18n:check-ratio。翻译校验与 QAvalidate_translation.py翻译校验器将任意语言 JSON 与en.json逐键比对并报告问题scripts/i18n/validate_translation.py# 快速检查只输出计数 python3 scripts/i18n/validate_translation.py quick -l cs # 输出 # Missing: 0 # Untranslated: 0 # Ignored (UNTRANSLATABLE_KEYS): 236 # 按命名空间输出详细 diff python3 scripts/i18n/validate_translation.py diff common -l cs python3 scripts/i18n/validate_translation.py diff settings -l cs # 导出 CSV / Markdown python3 scripts/i18n/validate_translation.py csv -l cs report.csv python3 scripts/i18n/validate_translation.py md -l cs report.md # 完整报告默认模式 python3 scripts/i18n/validate_translation.py -l cs检测项Missing keysen.json有而 locale 文件没有的键硬错误Extra keyslocale 文件有而en.json没有的键Untranslated keys译文值与英文源完全相同的键白名单除外软警告Placeholder mismatches源与译文之间 ICU 占位符不一致。退出码约定退出码含义0OK1一般错误2有缺失字符串硬错误3未翻译警告软错误语言可通过环境变量TRANSLATION_LANGcs或-l cs参数指定。check_translations.py代码—JSON 键核对器扫描src/**/*.tsx与src/**/*.ts中的useTranslations()调用核对所有被引用的键是否存在于en.jsonscripts/i18n/check_translations.pypython3 scripts/i18n/check_translations.py # 基础检查 python3 scripts/i18n/check_translations.py --verbose # 详细输出 python3 scripts/i18n/check_translations.py --fix # 自动把缺失键补进 en.jsongenerate-qa-checklist.mjs静态分析 QA扫描 Next.js 页面文件中的 i18n 风险指标并生成 Markdown 报告scripts/i18n/generate-qa-checklist.mjsnode scripts/i18n/generate-qa-checklist.mjs检查项固定宽度 class 滥用文本溢出风险、方向性 left/right classRTL 风险、易裁切模式、locale 键齐平度与en.json相比的缺失/多余键、优先语言es、fr、de、ja、arREADME 语言选择条。输出到docs/reports/i18n-qa-checklist-{date}.md。run-visual-qa.mjsPlaywright 视觉 QA用 Playwright 对多个 locale × 多个视口的仪表盘路由截图并评估页面健康度scripts/i18n/run-visual-qa.mjs# 默认es, fr, de, ja, ar目标 localhost:20128 node scripts/i18n/run-visual-qa.mjs # 自定义 base URL 与语言 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 布局错乱。输出docs/reports/i18n-visual-qa-{date}.md JSON 报告。不可翻译键的管理untranslatable-keys.json文件scripts/i18n/untranslatable-keys.json——应保持与英文源一致的键白名单validate_translation.py运行时加载它以避免把本来就英文的键误报为未翻译当前仓库中共236 个键与quick检查输出的Ignored (UNTRANSLATABLE_KEYS): 236一致{ description: Keys that should remain untranslated..., keys: [ common.model, common.oauth, health.cpu, ... ] }什么键应该进白名单品牌/产品名landing.brandName、common.social-github技术术语/缩写health.cpu、mcpDashboard.pid、settings.aiICU/格式化字符串apiManager.modelsCount、health.millisecondsShort占位示例值providers.openaiBaseUrlPlaceholder、cliTools.baseUrlPlaceholder协议名common.http、common.oauth、providers.oauth2Label导航分区名sidebar.primarySection、sidebar.cliSection。添加方式直接编辑该文件的keys数组然后重跑校验。该白名单历史上曾是validate_translation.py里的内联 Python set已外置为 JSON 便于维护。CI 集成CI 工作流定义在 .github/workflows/ci.yml对每次 push/PR 做翻译校验。从源码结构看当前管线比早期固定 i18n-matrix 任务演进为路径分流模式变更分类changes步骤基于git diff将变更分为code/i18n/workflow等类别纯docs/i18n变更走专用 i18n 任务不会触发昂贵的代码回归任务per-locale 校验对每个 locale 运行validate_translation.py quick -l lang一致性门禁code 路径npm run check:cli-i18n——CLI i18n 一致性硬门禁node scripts/i18n/check-translation-drift.mjs --warn——翻译漂移检查当前为 warn 级别check-translation-drift.mjs 即npm run i18n:check对应的门禁脚本非零退出即表示.i18n-state.json与磁盘镜像漂移。早期文档示例的矩阵发现逻辑供理解机制参考# 发现所有非 en 的 locale LANGS$(ls src/i18n/messages/*.json | xargs -n1 basename | sed s/.json$// | grep -v ^en$) # 逐语言校验 python3 scripts/validate_translation.py quick -l ${{ matrix.lang }}仪表盘汇总输出形如## Translations | Metric | Value | |--------|------| | Languages checked | 51 | | Total untranslated | 0 |文件结构总览config/ ├── i18n.json # locale 清单事实源51 locales rtl uiOnly/docsExcluded └── i18n-schema.json # i18n.json 的 JSON Schema src/i18n/ ├── config.ts # 薄类型适配器LOCALES/LANGUAGES/RTL_LOCALES/LOCALE_ALIASES ├── request.ts # 运行时 locale 解析 EN 双层兜底深合并 ├── resolveRequestedLocale.ts # cookie/header → locale 归一化含别名表 └── messages/ ├── en.json # 英文源~2800 键 ├── cs.json de.json pt.json ... # 共 51 个 locale 文件 └── zh-TW.json scripts/i18n/ ├── run-translation.mjs # v3.8.0 哈希增量 LLM 文档翻译管线推荐 ├── generate-multilang.mjs # Google Translate 引擎messages/readme 模式 ├── i18n_autotranslate.py # LLM 文档润色翻译器 ├── validate_translation.py # 翻译校验器quick/diff/csv/md ├── check_translations.py # 代码—JSON 键核对器 ├── check-translation-drift.mjs # CI 漂移门禁npm run i18n:check ├── sync-ui-keys.mjs # __MISSING__: 哨兵回填 ├── check-ui-keys-coverage.mjs / check-ui-value-drift.mjs / check-translation-ratio.mjs ├── check-glossary-consistency.mjs / glossary/ / glossary-normalize.mjs ├── generate-qa-checklist.mjs # 静态分析 QA ├── run-visual-qa.mjs # Playwright 视觉 QA ├── add-locale.mjs # 新增语言脚手架npm run i18n:add-locale ├── sync-language-bars.mjs # 语言条同步npm run i18n:sync-bars └── untranslatable-keys.json # 不可翻译键白名单236 键 .github/workflows/ └── ci.yml # 变更分类 i18n 校验 CLI i18n 门禁 docs/ ├── guides/I18N.md # 本指南英文源 ├── i18n/ │ ├── README.md # 自动生成的语言索引勿手改 │ ├── pt/docs/guides/I18N.md # 本指南的葡语镜像 │ └── ... # 其余 locale 目录 └── reports/ ├── i18n-qa-checklist-*.md # 静态分析报告 └── i18n-visual-qa-*.md # 视觉 QA 报告最佳实践编辑翻译时永远先改en.json——它是事实源运行翻译生成器把新键传播到各语言UI 用generate-multilang.mjs messages文档用npm run i18n:run复核自动翻译——机器翻译是起点而非终稿提交前校验python3 scripts/i18n/validate_translation.py quick -l lang若某键应保持英文把它加入untranslatable-keys.json。占位符安全Placeholder SafetyICU 占位符{count}、{value}、{total}、{seconds}必须逐字保留复数格式{count, plural, one {# model} other {# models}}必须保持结构校验器会自动检测占位符失配视觉 QA 与静态 QA 兜底排版风险。在代码中新增翻译键// 使用命名空间键 const t useTranslations(settings); t(cacheSettings); // 映射到 JSON 中的 settings.cacheSettings // 提交前运行键核对 python3 scripts/i18n/check_translations.py --verboseRTL 注意事项ar、he以及config/i18n.json中列出的fa、ur为 RTL locale避免硬编码left/rightCSS——使用start/end逻辑属性run-visual-qa.mjs会捕捉 RTL 布局错乱。已知问题与历史in.json→hi.json修复已演进生成器最初用 Google Translate 的遗留代码in表示印地语而非正确的 ISO 639-1 代码hi导致产出一个孤儿文件in.json与hi.json内容重复。修复方式是把LOCALE_SPECS中code: in改为code: hi并删除孤儿文件。当前仓库的更优雅处理是in被保留为印尼语id的别名见 config/i18n.json 中id条目的aliases: [in]遗留 Cookie 依旧能正确解析不会再落到印地语。docs/i18n/README.md是自动生成的该文件由文档翻译管线整体重新生成——它是全部文档的语言索引任何手动编辑都会丢失。需要持久化的人写文档请放在 docs/guides/I18N.md 及其各语言镜像中。不可翻译键外置untranslatable-keys.json白名单从validate_translation.py内的内联 Python set 迁移为外部 JSON 文件校验器在运行时加载便于独立维护当前 236 键。validate_translation.py的 Ignored 计数输出quick检查现在会显示白名单中被关闭的键数Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236小结OmniRoute 的 i18n 体系可归纳为一份 JSON 事实源config/i18n.json 薄适配器运行时src/i18n/request.ts 的 Cookie/请求头解析、别名归一化与 EN 双层兜底 双引擎翻译管线Google Translate 的 generate-multilang.mjs 管 UI 字符串v3.8.0 哈希增量 run-translation.mjs 管文档 四层质量门validate_translation.py 键校验、check_translations.py 代码核对、generate-qa-checklist.mjs 静态风险、run-visual-qa.mjs 视觉截图。掌握这套工具链你既能为仪表盘新增第 52 种语言也能让 51 种语言的翻译质量在 CI 中长期保持0 缺失、0 未翻译。【免费下载链接】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项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考