OmniRoute 多语言i18n体系全解析语言架构、自动翻译管线与质量保障工具链【免费下载链接】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 为核心系统讲解该项目如何以en.json为唯一事实来源通过next-intl Cookie 解析支撑数十种语言的完整仪表盘界面翻译、多语言文档与 RTL 布局并深入拆解两条自动翻译管线Google Translate 引擎与 LLM 引擎、四个质量验证工具以及 CI 中的多语言矩阵校验。读完本文你将掌握如何新增一种语言、如何验证翻译完整性、如何防止占位符与 RTL 布局回归的完整可操作方案。核心架构单一事实来源与运行时解析Source of Truth事实来源OmniRoute 的国际化遵循严格的单一事实来源Source of Truth原则全部 UI 字符串以英文为基准UI 字符串源src/i18n/messages/en.json英文源约 2800 个键124 个顶层命名空间语言文件src/i18n/messages/ 下的{locale}.json每种语言一个文件框架next-intl基于 Cookie 的 locale 解析配置src/i18n/config.ts 定义语言列表、语言名称与旗帜图标。值得特别说明的是当前仓库中的配置已演进为双源结构src/i18n/config.ts文件头部注释明确指出真正的 Source of Truth 是 config/i18n.json该 JSON 同时被scripts/i18n/run-translation.mjs文档翻译管线消费而config.ts只是一个薄类型适配器不维护手写语言列表src/i18n/config.ts。它向外导出LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES以及LOCALE_COOKIE NEXT_LOCALE等常量src/i18n/config.ts。从 config/i18n.json 可以看到当前仓库实际支持的语言集合已远不止文档最初记载的 30 种达到 50 个 locale 条目每个条目包含code、label、name、native、english、flag六个字段部分语言还声明了aliases别名如uk-UA的别名uk、id的别名in、zh-TW的别名zh-hk/zh-mo/zh-hant。同时该配置声明了rtl数组当前为[ar, fa, he, ur]——即阿拉伯语、波斯语、希伯来语、乌尔都语四种 RTL 语言这比文档表格中仅列出ar/he更为完整。运行时解析流程Runtime Flow结合 src/i18n/request.ts 的实现运行时 locale 解析按以下顺序进行用户在界面选择语言 → 写入NEXT_LOCALECookie服务端getRequestConfig先读 Cookie若 Cookie 为空则读取x-locale请求头src/i18n/request.ts交由 resolveRequestedLocale 解析命中已配置 locale 直接返回否则做小写归一化精确匹配再遍历aliases表做别名映射例如旧 Cookiein自动映射到id裸标签uk映射到uk-UA全部失败则回退到默认en动态import加载messages/{locale}.json组件内使用useTranslations(namespace)t(key)取字符串。此外request.ts 还实现了两套回退保护__MISSING__:哨兵回退scripts/i18n/sync-ui-keys.mjs在为语言文件回填未翻译键时会写入__MISSING__:英文值前缀deepMergeFallback在合并时遇到此类哨兵值视其为缺失从而让干净的英文值胜出避免把未翻译内容当成最终文案对应 issue #7258命名空间级回退当活动语言不是默认语言时以{ ...enMessages, ...mergedMessages }做顶层浅合并确保新加入的命名空间如cliCode、cliAgents、acpAgents等在翻译未就绪前先以英文展示不会白屏。支持的语言列表文档中给出了如下语言对照表含 RTL 标记与 Google Translate 代码当前仓库的config/i18n.json在此基础上已扩充更多 localeCodeLanguageRTLGoogle Translate CodearالعربيةYesarbgБългарскиNobgcsČeštinaNocsdaDanskNodadeDeutschNodeesEspañolNoesfiSuomiNofifrFrançaisNofrheעבריתYesiwhiहिन्दीNohihuMagyarNohuidBahasa IndonesiaNoiditItalianoNoitja日本語Nojako한국어NokomsBahasa MelayuNomsnlNederlandsNonlnoNorskNonophiFilipinoNotlplPolskiNoplptPortuguês (Portugal)Noptpt-BRPortuguês (Brasil)NoptroRomânăNororuРусскийNoruskSlovenčinaNosksvSvenskaNosvthไทยNothtrTürkçeNotruk-UAУкраїнськаNoukviTiếng ViệtNovizh-CN中文 (简体)Nozh-CN注上表为原文档记载的 30 种语言基线当前仓库 config/i18n.json 已扩展到 50 条目新增az、bn、el、et、fa、ga、gu、hr、lt、lv、mr、mt、sl、sr、sw、ta、te、ur、zh-TW等并且fa/ur也被纳入rtl列表读者应以配置文件为准。快速参考命令一览任务命令生成翻译node scripts/i18n/generate-multilang.mjs messagesLLM 翻译文档python3 scripts/i18n_autotranslate.py --api-url url --api-key key --model model校验某个语言python3 scripts/validate_translation.py quick -l cs检查代码键python3 scripts/check_translations.py生成 QA 报告node scripts/i18n/generate-qa-checklist.mjs可视化 QAPlaywrightnode scripts/i18n/run-visual-qa.mjs新增一种语言的完整流程1. 注册 Locale编辑 src/i18n/config.ts// 加入 LOCALES 数组 xx, // 加入 LANGUAGES 数组 { code: xx, label: XX, name: Language Name, flag: ️ },需要提示的是由于当前仓库已将config.ts重构为 config/i18n.json 的薄适配层新增语言更推荐的做法是直接在 config/i18n.json 的locales数组中补充{ code, label, name, native, english, flag }条目并按需把该语言加入rtl数组若为 RTL 语言或补充aliases。若该语言仅用于 UI 而暂不翻译文档可将其加入uiOnly数组。2. 加入生成器编辑scripts/i18n/generate-multilang.mjs在LOCALE_SPECS数组中加入条目{ code: xx, googleTl: xx, label: XX, flag: ️, languageName: Language Name, readmeName: Language Name, docsName: Language Name, },googleTl字段用于指定该语言在 Google Translate 中使用的目标语言代码例如pt-BR使用pt、uk-UA使用uk、phi使用tl可参考LOCALE_SPECS中已有的en/pt-BR/es/fr等条目写法scripts/i18n/generate-multilang.mjs。3. 生成初始翻译node scripts/i18n/generate-multilang.mjs messages该命令会基于en.json通过 Google Translate 自动翻译生成src/i18n/messages/xx.json。4. 人工审校自动翻译自动翻译只是起点需人工逐条检查技术准确性术语、专有名词是否译错是否符合语境同一英文词在不同命名空间应有不同译法占位符是否正确保留{count}、{value}等不能被改写或删除。5. 校验python3 scripts/validate_translation.py quick -l xx python3 scripts/validate_translation.py diff common -l xx6. 生成翻译文档node scripts/i18n/generate-multilang.mjs docs自动翻译管线OmniRoute 的 i18n 工具有两条并行的自动翻译管线以 Google Translate 免费接口为主的生成器以及以任意 OpenAI 兼容 LLM包括 OmniRoute 自身为后端的高质量翻译器。generate-multilang.mjsGoogle Translate 引擎这是项目最早的主自动翻译引擎使用 Google Translate 免费 API 为 UI 字符串、README 与文档生成翻译node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]模式功能messages从en.json翻译src/i18n/messages/{locale}.json中缺失的键readme将README.md翻译为项目根目录下的README.{code}.mddocs将DOC_SOURCE_FILES翻译到docs/i18n/{locale}/{docName}all依次执行以上三种模式该脚本共 1041 行实现了多项工程化能力文本保护翻译前先屏蔽代码块、行内代码、Markdown 链接/图片text、HTML 标签、表格以及 ICU 占位符{count}、{value}、{total}等翻译完成后再恢复原样分批合并请求用__OMNIROUTE_I18N_SEPARATOR__分隔符拼接多条字符串单次请求不超过 1800 字符最大限度减少 API 调用次数内存缓存会话内对重复字符串去重避免重复请求指数退避重试对 429/5xx 错误最多重试 5 次延迟为 300ms × 尝试次数超时控制单请求 20 秒超时跳过已存在文件目标文件已存在时不会覆盖。重要行为说明docs/i18n/README.md每次运行都会被重新生成——它是所有文档的自动索引根目录的README.{code}.md仅在不存在时创建会跳过EXISTING_README_CODES中列出的语言语言切换条 **Languages:** ...会自动插入/更新到所有已翻译文档中。重要演进提示该脚本文件头部已声明DEPRECATED 2026-05-13scripts/i18n/generate-multilang.mjs提示文档翻译应改用npm run i18n:run即scripts/i18n/run-translation.mjsdocs模式将在 v3.10 移除messages与readme模式仍由该脚本承担。run-translation.mjs新版哈希增量文档翻译管线作为 Google Translate 引擎的替代者scripts/i18n/run-translation.mjs 采用基于哈希的增量翻译状态文件.i18n-state.json记录每个源文件与目标文件的 SHA-256 哈希重复运行时只重译源哈希变化或目标缺失的文件。其文档头部给出了完整的用法scripts/i18n/run-translation.mjsnpm run i18n:run # 全量增量翻译 npm run i18n:run -- --localept-BR # 只翻译某语言 npm run i18n:run -- --filesCLAUDE.md,docs/ARCHITECTURE.md # 只翻译指定文件 npm run i18n:run -- --force # 忽略哈希强制全量重译 npm run i18n:run:dry # 预演不实际调用 npm run i18n:run -- --adopt # 从磁盘重建状态不调用 API后端通过环境变量配置密钥不入库、不进日志OMNIROUTE_TRANSLATION_API_URL 例如 https://cloud.omniroute.dev/v1 OMNIROUTE_TRANSLATION_API_KEY 鉴权 token OMNIROUTE_TRANSLATION_MODEL 例如 cx/gpt-5.6-sol OMNIROUTE_TRANSLATION_TIMEOUT_MS 可选默认 60000 OMNIROUTE_TRANSLATION_CONCURRENCY 可选默认 4翻译目标落在docs/i18n/locale/...镜像源文件布局每个文件带 H1 头、语言条和---分隔符。该工具链还配套了 scripts/i18n/lib/language-bar.mjs语言条构建、scripts/i18n/lib/translation-state.mjs哈希状态管理等库模块。i18n_autotranslate.pyLLM 翻译引擎这是次级翻译器使用任意 OpenAI 兼容 LLM API包括 OmniRoute 自身翻译现有的docs/i18n/Markdown 文件适合在 Google Translate 质量之上做打磨或重译python3 scripts/i18n_autotranslate.py \ --api-url http://localhost:20128/v1 \ --api-key sk-your-key \ --model gpt-4o特性扫描docs/i18n/下的 Markdown 文件定位英文段落跳过代码块、表格与已翻译内容将段落连同技术翻译系统提示词发送给 LLM支持全部已配置语言。验证与 QA 工具链validate_translation.py翻译校验器该 Python 校验器将任意语言 JSON 与en.json对比并输出问题报告源码共 635 行# 快速检查仅统计数量 python3 scripts/validate_translation.py quick -l cs # 输出 # Missing: 0 # Untranslated: 0 # Ignored (UNTRANSLATABLE_KEYS): 236 # 按分类查看详细差异 python3 scripts/validate_translation.py diff common -l cs python3 scripts/validate_translation.py diff settings -l cs # 导出 CSV python3 scripts/validate_translation.py csv -l cs report.csv # 导出 Markdown python3 scripts/validate_translation.py md -l cs report.md # 完整报告默认 python3 scripts/validate_translation.py -l cs可检测的四类问题缺失键Missing keys——存在于en.json但语言文件缺失多余键Extra keys——语言文件存在但en.json没有未翻译键Untranslated keys——语言值与英文源相同排除允许列表占位符不匹配Placeholder mismatches——源与翻译之间的 ICU 占位符不一致。退出码语义Code含义0OK1通用错误2缺失字符串硬错误3未翻译警告软性环境变量设置TRANSLATION_LANGcs或使用-l cs参数均可指定目标语言scripts/i18n/validate_translation.py。占位符检测使用正则\{\s*([a-zA-Z][a-zA-Z0-9_]*)仅提取顶层占位符变量名避免对 ICU 内部已翻译文本产生误报scripts/i18n/validate_translation.py。check_translations.py代码键校验器扫描src/**/*.tsx与src/**/*.ts中的useTranslations()调用验证所有被引用的键都存在于en.json# 基础检查 python3 scripts/check_translations.py # 详细输出 python3 scripts/check_translations.py --verbose # 自动修复把缺失键补进 en.json python3 scripts/check_translations.py --fixgenerate-qa-checklist.mjs静态分析 QA扫描 Next.js 页面文件针对 i18n 风险指标生成 Markdown 报告node scripts/i18n/generate-qa-checklist.mjs检查项包括固定宽度 class 的使用溢出风险方向性 left/right classRTL 风险易裁剪clipping模式语言一致性相对en.json的缺失/多余键优先语言es、fr、de、ja、arREADME 语言选择条是否存在。输出docs/reports/i18n-qa-checklist-{date}.md。run-visual-qa.mjsPlaywright 可视化 QA通过 Playwright 对多个语言与视口下的所有仪表盘路由截图并评估页面健康度# 默认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可检测文本溢出Text overflow元素裁剪Element clippingRTL 布局错位RTL layout mismatches。输出docs/reports/i18n-visual-qa-{date}.md JSON 报告。管理不可翻译键Untranslatable Keysuntranslatable-keys.json文件scripts/i18n/untranslatable-keys.json这是应保持与英文源完全一致的键允许列表由validate_translation.py在运行时加载scripts/i18n/validate_translation.py以避免把本就不该翻译的键误报为未翻译警告。其 JSON 结构包含description与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。新增键的方法编辑 scripts/i18n/untranslatable-keys.json 的keys数组后重新运行校验。CI 集成GitHub Actions.github/workflows/ci.ymlCI 流水线在每次 push 和 PR 上校验全部语言i18n-matrixjob——动态发现所有语言文件排除en.jsoni18njob——为每个语言并行执行validate_translation.py quick -l langci-summaryjob——汇总结果到仪表盘摘要。# i18n-matrix: 发现语言 LANGS$(ls src/i18n/messages/*.json | xargs -n1 basename | sed s/.json$// | grep -v ^en$) # i18n: 逐个校验语言 python3 scripts/validate_translation.py quick -l ${{ matrix.lang }}仪表盘输出示例## Translations | Metric | Value | |--------|------| | Languages checked | 30 | | Total untranslated | 0 | ✅ All translations complete文件结构总览src/i18n/ ├── config.ts # Locale 定义语言列表、RTL 配置薄适配层 ├── request.ts # 运行时 locale 解析 ├── resolveRequestedLocale.ts # Cookie/Header 到 locale 的纯函数解析含别名 ├── detectBrowserLocale.ts # 客户端浏览器语言检测 └── messages/ ├── en.json # 事实来源约 2800 键 ├── cs.json # 捷克语翻译 ├── de.json # 德语翻译 └── ... # 全部语言文件 scripts/ ├── i18n/ │ ├── generate-multilang.mjs # 自动翻译引擎Google Translate1041 行已标记弃用 │ ├── run-translation.mjs # 新版哈希增量文档翻译管线 │ ├── generate-qa-checklist.mjs # 静态分析 QA │ ├── run-visual-qa.mjs # Playwright 可视化 QA │ ├── untranslatable-keys.json # 校验允许列表约 236 键 │ └── lib/ # language-bar / translation-state 等共享库 ├── validate_translation.py # 翻译校验器 ├── check_translations.py # 代码键校验器 └── i18n_autotranslate.py # LLM 文档翻译器 .github/workflows/ └── ci.yml # CI 矩阵中的 i18n 校验 docs/ ├── guides/ │ └── I18N.md # 本文档手写维护的 i18n 工具链说明 ├── i18n/ │ ├── README.md # 自动生成的语言索引勿手改 │ ├── cs/docs/I18N.md # 各语言文档镜像 │ └── ... # 语言目录 └── reports/ ├── i18n-qa-checklist-*.md # 静态分析报告 └── i18n-visual-qa-*.md # 可视化 QA 报告完整的 UI 字符串历史对照可参考 docs/i18n 各语言目录下的翻译镜像以及 config/i18n.json 这一权威语言清单。最佳实践编辑翻译时的铁律永远先改en.json——它是事实来源运行generate-multilang.mjs messages把新键传播到所有语言人工审校自动翻译——Google Translate 是起点而非终点提交前先校验python3 scripts/validate_translation.py quick -l lang若某键应保持英文更新untranslatable-keys.json。占位符安全ICU 占位符{count}、{value}、{total}、{seconds}必须原样保留复数格式{count, plural, one {# model} other {# models}}必须维持结构完整校验器会自动检测占位符不匹配无需人工逐条比对。在代码中新增翻译键// 使用带命名空间的键 const t useTranslations(settings); t(cacheSettings); // 映射到 JSON 中的 settings.cacheSettings // 运行 check_translations.py 验证键存在 python3 scripts/check_translations.py --verboseRTL 注意事项RTL 语言为阿拉伯语ar、波斯语fa、希伯来语he、乌尔都语ur以 config/i18n.json 的rtl数组为准避免硬编码left/rightCSS改用逻辑属性start/endrun-visual-qa.mjs可捕获 RTL 布局错位建议纳入发布前检查。已知问题与历史Known Issues Historyin.json→hi.json修复生成器最初为印地语使用code: inGoogle Translate 已弃用的代码而正确的 ISO 639-1 代码是hi。这曾产生一个孤立的in.json与hi.json重复。修复方式在generate-multilang.mjs中将code: in改为code: hi并删除孤立文件。该问题最初由上游提交952b0b22cdiegosouzapw引入。当前仓库为兼容旧 Cookie已在 config/i18n.json 中为id声明别名in使旧标签仍可解析。docs/i18n/README.md为自动生成该文件由generate-multilang.mjs docs及新版run-translation.mjs完全重新生成任何手动编辑都会被覆盖。需要持久化保存的手写文档应放在docs/guides/I18N.md即本文档这样的路径中。不可翻译键列表外置化untranslatable-keys.json允许列表最初是validate_translation.py中的内联 Python 集合后迁移到外部 JSON 文件以便维护校验器在运行时加载。validate_translation.py忽略计数输出quick检查现在会展示来自untranslatable-keys.json的被忽略键数量Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236结语OmniRoute 的国际化体系是一条从单一英文事实来源出发、经过自动翻译管线 哈希增量重译生产、再由静态校验 代码键扫描 可视化截图多重 QA 兜底的完整流水线。新增一种语言只需六步即可闭环而 RTL 语言、占位符与不可翻译键的三类特殊处理保证了翻译质量和界面健壮性。对于希望为自有项目搭建可持续国际化工具链的开发者本文的架构分层、命令矩阵与 CI 集成模式均可直接借鉴。【免费下载链接】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），仅供参考