OmniRoute 国际化（i18n）体系全解：多语言 UI、文档翻译流水线与质量门禁

OmniRoute 国际化i18n体系全解多语言 UI、文档翻译流水线与质量门禁【免费下载链接】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/OmniRouteOmniRoute 内置了一套覆盖 Dashboard 界面、CLI 命令与全套技术文档的国际化i18n工程体系当前仓库内置 42 个语言文件以英文en.json为唯一源语言并提供一条命令新增语言LLM 哈希增量翻译CI 全量校验等完整的工具链。本文以 docs/i18n/es/docs/guides/I18N.md及其英文母版 docs/guides/I18N.md为骨架结合仓库源码逐层拆解其架构、运行时解析、自动翻译管线、校验工具与最佳实践读完即可掌握 OmniRoute 多语言系统的完整使用与维护方法。一、全景速览一条命令对应一个 i18n 任务OmniRoute 的 i18n 工具链由 Node.js.mjs与 Python.py两类脚本构成分布在scripts/i18n/目录下并在 package.json 中以i18n:*脚本统一封装。下表是官方快速参考命令路径已按当前仓库实际位置校正任务命令全链路新增一种语言配置 → 文档 → CLI → 站点npm run i18n:add-locale -- --codeel …翻译文档推荐哈希增量npm run i18n:run翻译 UI 字符串补齐缺失 keynpm run i18n:sync-ui -- --translate-markers --batch-size40检查翻译漂移driftnpm run i18n:check真实翻译比例门禁npm run i18n:check-ratio重新生成 语言导航条npm run i18n:sync-bars校验某个语言quick 模式python3 scripts/i18n/validate_translation.py quick -l cs检查代码中的 key 是否存在于 JSONpython3 scripts/i18n/check_translations.py生成静态 QA 报告node scripts/i18n/generate-qa-checklist.mjsPlaywright 可视化 QAnode scripts/i18n/run-visual-qa.mjs需要注意的是仓库当前已经演进到LLM 哈希增量翻译为主管线老旧的 Google Translate 生成器 scripts/i18n/generate-multilang.mjs 已在文件头标注DEPRECATED见下文自动翻译流水线一节实际使用的脚本路径统一为scripts/i18n/下各文件。二、架构从单一数据源到运行时渲染2.1 单一数据源Source of TruthOmniRoute 的 i18n 数据源遵循严格的单点声明、处处派生原则UI 字符串src/i18n/messages/en.json—— 英文源语言文件约 2800 个 key语言文件src/i18n/messages/{locale}.json共 42 个含en.json源文件即 41 种翻译语言框架next-intl基于 Cookie 的 locale 解析配置声明config/i18n.json—— 唯一的 locale 声明点包含默认语言、RTL 列表与全部语言元数据。关键设计体现在 src/i18n/config.ts 的头部注释中该文件是config/i18n.json的薄类型适配器thin typed adapter明确要求不要在这里手写维护语言列表。这意味着要新增语言唯一正确的入口是编辑config/i18n.json。从源码结构看config/i18n.json还支持aliases浏览器/OS 语言标签映射如id声明aliases: [in]与rtl列表等元数据均被 src/i18n/config.ts 解析为LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES等导出常量。2.2 运行时解析流程Runtime Flow语言解析发生在 src/i18n/request.ts基于next-intl的getRequestConfig其流程为用户选择语言 → 写入NEXT_LOCALEcookiecookie 名由LOCALE_COOKIE常量定义src/i18n/request.ts 依次解析优先读NEXT_LOCALEcookie其次读x-locale请求头再交给resolveRequestedLocale完成规范化含别名映射与默认值回退动态import(./messages/${locale}.json)加载对应语言包组件通过useTranslations(namespace)与t(key)取用翻译。值得展开的是它的分层回退fallback机制src/i18n/request.ts 中的deepMergeFallback会以英文包兜底任何缺失 key此外还处理了同步脚本写入的__MISSING__:哨兵前缀见 src/i18n/request.ts——当某个 key 尚未翻译时同步工具会以__MISSING__:英文原文占位运行时则自动以干净英文回退。normalizeComplianceEventTypes还负责将合规事件类型中带点号的扁平 key 规范化为嵌套结构。这意味着部分翻译partial translation是合法的语言包缺 key 不会导致崩溃只会显示英文。2.3 支持的 42 种语言以下语言表取自仓库真实声明文件 config/i18n.jsonrtl一列与文件中的rtl: [ar, fa, he, ur]一致注意当前配置比西语文档所列多了fa、ur两个 RTL 语言代码语言RTLGoogle Translate 代码arالعربية是arazAzərbaycan dili否azbgБългарски否bgbnবাংলা否bncsČeština否csdaDansk否dadeDeutsch否deenEnglish否enesEspañol否esfaفارسی是fafiSuomi否fifrFrançais否frguગુજરાતી否guheעברית是iwhiहिन्दी否hihuMagyar否huidBahasa Indonesia否iditItaliano否itja日本語否jako한국어否komrमराठी否mrmsBahasa Melayu否msnlNederlands否nlnoNorsk否nophiFilipino否tlplPolski否plptPortuguês (Portugal)否ptpt-BRPortuguês (Brasil)否ptroRomână否roruРусский否ruskSlovenčina否sksvSvenska否svswKiswahili否swtaதமிழ்否tateతెలుగు否tethไทย否thtrTürkçe否truk-UAУкраїнська否ukurاردو是urviTiếng Việt否vizh-CN中文 (简体)否zh-CNzh-TW中文 (繁體)否zh-TW对应的 42 个语言文件均可在 src/i18n/messages/ 中逐一找到与上表一一对应。三、如何新增一门语言一条命令全链路注册新版流程v3.8把新增语言收敛为一条命令不再需要手工改动多个文件# 需要 .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 # 仅预览将要执行的写入不产生任何文件或网络请求 node scripts/i18n/add-locale.mjs --codeel --englishGreek --nativeΕλληνικά --flag --dry-run从 scripts/i18n/add-locale.mjs 源码看一条命令内部按8 个阶段phases顺序执行每个阶段都会先检查目标是否已存在因此对已注册语言重复执行是安全的空操作config → flag → ui → docs → cli → readme → bars → site阶段作用config在 config/i18n.json 中写入 locale 条目含 aliases、rtl——唯一数据源flag若缺失则从 flag-iconsMIT拉取docs/assets/flags/cc.svgui生成src/i18n/messages/code.json脚手架并调用sync-ui-keys --translate-markers补齐翻译残留__MISSING__标记会导致退出码 1docs通过run-translation翻译文档核心集lib/docs-core-set.mjs并生成llm.txt/CHANGELOG.md镜像桩cli生成bin/cli/locales/code.json脚手架并批量翻译commonprogram段落readme更新 README 旗标链接、docs/i18n/README.md行、本文档docs/guides/I18N.md的语言表行及各处的语言计数bars通过sync-language-bars为所有 语言导航条加入新语言site可选为站点 checkout 生成lang/code.json并更新语言下拉框翻译类阶段ui、docs、cli、site依赖OMNIROUTE_TRANSLATION_API_URL、_API_KEY、_MODEL三个环境变量.env会被自动加载子脚本通过execFileSync以参数数组方式执行任何内容都不会被插值进 shell从实现层面杜绝了命令注入。新增完成后需要运行一组验证门禁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双向校验配置中的语言必须有对应表面条目、条目必须能映射回配置语言防止新增语言在某个表面文档索引、README 行等漏注册。四、自动翻译流水线4.1 主管线LLM 哈希增量翻译推荐v3.8.0 起当前主推的文档翻译方案是基于 OpenAI 兼容 LLM 端点的哈希增量翻译器# 增量翻译只触碰发生过变化的源文件 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 # 预演将要发生什么不发 API 请求、不写文件 npm run i18n:run:dry # CI 门禁——状态漂移时以非零退出码失败 npm run i18n:check其核心机制包括状态跟踪提交到仓库的.i18n-state.json为每个源文件 × 每个语言记录 SHA-256 哈希i18n:check的漂移检测完全离线、确定性强不发任何 API 调用再引导re-adoptnpm run i18n:run -- --adopt从磁盘上已有的镜像重建.i18n-state.json不发请求也不写.md适合只改了链接列表/数字但无需重译或状态文件丢失的场景可配合--files/--locale与--dry-run使用输出形状每个翻译后的文件顶部固定为# 标题 (native)行 Languages 语言条 ---分隔线 翻译正文该格式与scripts/check/check-docs-sync.mjs对llm.txt和CHANGELOG.md镜像的强制要求保持一致。后端配置写在.env中绝不提交到仓库环境变量用途OMNIROUTE_TRANSLATION_API_URLOpenAI 兼容 base URL如…/v1OMNIROUTE_TRANSLATION_API_KEYbearer token日志中脱敏OMNIROUTE_TRANSLATION_MODEL模型 ID例如cx/gpt-5.4-miniOMNIROUTE_TRANSLATION_TIMEOUT_MS可选默认60000OMNIROUTE_TRANSLATION_CONCURRENCY可选默认4UI 字符串的翻译走独立的同步工具# 为所有语言包补齐缺失/占位 UI key npm run i18n:sync-ui -- --translate-markers --batch-size404.2 旧版脚本已弃用v3.10 移除仓库仍保留两套旧管线但均已标记弃用scripts/i18n/generate-multilang.mjsGoogle Translate 引擎文件头明确标注DEPRECATED 2026-05-13docs模式已被新 LLM 管线取代仅messages与readme模式暂留scripts/i18n/i18n_autotranslate.pyLLM 文档翻译扫描docs/i18n/下的英文段落、跳过代码块/表格/已翻译内容发送给任意 OpenAI 兼容 LLM也可用 OmniRoute 自身网关。官方明确建议不要再使用generate-multilang.mjs messages翻译 UI 字符串正确路径是 LLM 后端 i18n:sync-ui。这两套旧脚本的行为可参考其源码注释如 chunked batching 用__OMNIROUTE_I18N_SEPARATOR__分隔符合并多条字符串、单请求上限 1800 字符、指数退避最多重试 5 次、单请求 20 秒超时、已有目标文件不覆盖等但新改动请一律走新管线。五、校验与 QA四层质量门禁5.1 validate_translation.py —— 翻译正确性校验核心校验器将任意语言 JSON 与en.json对比# quick只输出统计 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有而语言文件没有的 keyExtra keys语言文件中有而en.json没有的 keyUntranslated keys语言值等于英文源值的 key排除 allowlistPlaceholder mismatches源与译文之间 ICU 占位符不一致。退出码语义可从 scripts/i18n/validate_translation.py 源码及文档确认退出码含义0OK1一般错误2缺失字符串硬错误3未翻译警告软错误环境变量TRANSLATION_LANGcs与-l cs参数等效。源码中可看到忽略清单UNTRANSLATABLE_KEYS是从scripts/i18n/untranslatable-keys.json加载的quick输出中的Ignored计数即该清单大小说明允许清单已外置为 JSON。5.2 check_translations.py —— 代码到 JSON 的 key 一致性扫描src/**/*.tsx与src/**/*.ts中的useTranslations()调用验证所有引用的 key 都存在于en.jsonpython3 scripts/i18n/check_translations.py # 基础检查 python3 scripts/i18n/check_translations.py --verbose # 详细输出 python3 scripts/i18n/check_translations.py --fix # 自动补写缺失 key 到 en.json5.3 generate-qa-checklist.mjs —— 静态分析 QA扫描 Next.js 页面文件中的 i18n 风险指标并生成 Markdown 报告node scripts/i18n/generate-qa-checklist.mjs检查项包括固定宽度 class 使用溢出风险、方向性 left/right classRTL 风险、易裁剪模式、语言 parity相对en.json的缺失/多余 key以及优先语言es、fr、de、ja、arREADME 中的语言选择条。输出到docs/reports/i18n-qa-checklist-{date}.md。5.4 run-visual-qa.mjs —— Playwright 可视化 QA对多个语言 × 多个视口下的所有 Dashboard 路由截图并评估页面健康度# 默认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 报告。5.5 术语表一致性Glossary除 key 对齐与 ICU 合法性之外仓库还维护了逐语言术语层用于捕获语义漂移例如同一英文概念provider在不同字符串中被译为两种不同的中文词。相关文件与命令npm run i18n:check-glossary # 默认检查 zh-CN 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机制要点见 scripts/i18n/check-glossary-consistency.mjsscripts/i18n/glossary/locale.json带版本号的术语表每个概念有canonical权威译法与可选的synonyms同义词列表目录中发现任何同义词即视为漂移synonyms为空数组表示已记录但暂未强制执行scripts/i18n/glossary/protected-terms.json产品/提供商/模型/协议/CLI/环境变量/标识符名单如OmniRoute、OAuth、MCP、A2A、DATA_DIR要求出现在任何译文值中都必须原样保留——这与untranslatable-keys.json按 key 排除整条检查粒度不同它是按概念在任意值内部检查核心函数checkGlossaryConsistency(localeMessages, glossary, protectedTerms)返回{ violations: [...] }违规类型为glossary-synonym非权威词或protected-term-altered受保护名被篡改并已接入 CI 的i18n-glossary-zhcn作业。六、不可翻译键的管理scripts/i18n/untranslatable-keys.json是允许保持英文原样的 key 清单用于避免校验器误报未翻译警告{ description: Keys that should remain untranslated..., keys: [ common.model, common.oauth, health.cpu ] }适合放进该清单的 key 类型品牌/产品名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。新增一个 key 只需编辑keys数组后重新运行校验。该清单在 scripts/i18n/validate_translation.py 启动时被加载为UNTRANSLATABLE_KEYS集合。七、CI 集成每次推送/PR 全量校验GitHub Actions 工作流.github/workflows/ci.yml在每次推送与 PR 时校验全部语言i18n-matrix作业动态发现所有语言文件排除en.jsonLANGS$(ls src/i18n/messages/*.json | xargs -n1 basename | sed s/.json$// | grep -v ^en$)i18n作业并行对每个语言运行validate_translation.py quick -l langpython3 scripts/i18n/validate_translation.py quick -l ${{ matrix.lang }}ci-summary作业聚合结果写入 dashboard 摘要## Translations | Metric | Value | |--------|------| | Languages checked | 30 | | Total untranslated | 0 | ✅ All translations complete此外还有i18n-ui-coverageUI key 覆盖率门禁跳过 draft PRi18n 或代码变更时运行与i18n-glossary-zhcn术语表门禁gating 方式与前者相同等独立作业。八、文件结构速览src/i18n/ ├── config.ts # config/i18n.json 的类型化薄适配器勿手改 ├── request.ts # 运行时 locale 解析 EN 回退 ├── resolveRequestedLocale.ts # 请求级 locale 规范化/别名映射 └── messages/ ├── en.json # 源语言约 2800 个 key ├── cs.json # 捷克语 ├── de.json # 德语 └── ... # 共 42 个语言文件 config/ └── i18n.json # 唯一语言声明点locales/rtl/aliases scripts/i18n/ ├── run-translation.mjs # 主翻译管线LLM 哈希增量 ├── add-locale.mjs # 一键新增语言 ├── sync-ui-keys.mjs # UI key 同步/补齐 ├── check-translation-drift.mjs # 漂移检测i18n:check ├── check-ui-keys-coverage.mjs # UI key 覆盖率 ├── check-translation-ratio.mjs # 真实翻译比例 ├── sync-language-bars.mjs # 语言条 ├── check-glossary-consistency.mjs ├── glossary/ # 术语表与受保护名词 ├── generate-multilang.mjs # 已弃用Google Translate ├── i18n_autotranslate.py # 已弃用LLM 文档翻译 ├── validate_translation.py # 翻译校验器 ├── check_translations.py # 代码 key 校验 ├── generate-qa-checklist.mjs # 静态 QA ├── run-visual-qa.mjs # 可视化 QA └── untranslatable-keys.json # 不可翻译键清单 docs/ ├── guides/I18N.md # 本指南英文母版手工维护 ├── i18n/README.md # 自动生成/维护的语言索引 ├── i18n/locale/ # 各语言文档镜像 └── reports/ # i18n-qa-checklist-* / i18n-visual-qa-* 报告九、最佳实践9.1 编辑翻译的正确顺序永远先改en.json—— 它是唯一源语言运行npm run i18n:sync-ui新管线将新 key 传播到所有语言包人工复核自动翻译——LLM/机器翻译只是起点不是终稿提交前校验python3 scripts/i18n/validate_translation.py quick -l lang若某 key 应保持英文更新untranslatable-keys.json。9.2 占位符安全ICU 占位符{count}、{value}、{total}、{seconds}必须原样保留复数格式{count, plural, one {# model} other {# models}}必须维持结构校验器会自动检测占位符不匹配。9.3 在代码中新增翻译 key// 使用命名空间 key const t useTranslations(settings); t(cacheSettings); // 映射到 JSON 中的 settings.cacheSettings // 提交前运行代码 key 校验 python3 scripts/i18n/check_translations.py --verbose9.4 RTL 注意事项当前config/i18n.json声明了ar、fa、he、ur四个 RTL 语言避免硬编码left/rightCSS改用start/end逻辑属性RTL 布局错位由run-visual-qa.mjs的可视化 QA 兜底。十、已知问题与演进历史这部分记录既有的坑与解法避免后续维护者重蹈覆辙in.json→hi.json修复生成器最初为印地语使用已废弃的 Google Translate 代码in正确应为 ISO 639-1 的hi产生了一个孤立的in.json重复文件。修复方式是把generate-multilang.mjs中的code: in改为code: hi并删除孤立文件。后续in又曾被用作Indonesian (Legacy)最终在 2026-09-02 从所有表面移除id声明aliases: [in]因此已保存的NEXT_LOCALEin或OMNIROUTE_LANGin会自动解析为iddocs/i18n/README.md的维护方式旧版本每次运行都会整体重建该索引任何手工编辑都会丢失新版改由i18n:add-locale原位插入新语言行并更新计数语句其余编辑全部手工进行并由tests/unit/i18n-locale-surfaces-parity.test.ts双向守护不可翻译键清单外置untranslatable-keys.json允许清单最初是validate_translation.py内联的 Python 集合后移为外部 JSON 文件便于维护校验器运行时加载quick输出新增 Ignored 计数quick检查现在会显示来自untranslatable-keys.json的忽略键数量Ignored (UNTRANSLATABLE_KEYS): 随版本变化。结语OmniRoute 的 i18n 体系以config/i18n.json单点声明、en.json单一源语言、next-intl运行时解析为底座配合i18n:add-locale一键注册、LLM 哈希增量翻译、validate_translation.py/check_translations.py/ 静态与可视化 QA / 术语表一致性等多层门禁最终在 CI 中全自动守护 42 种语言、数千个 UI key 与整套文档镜像的质量。无论是为 OmniRoute 贡献新语言还是在自己的项目中借鉴这套多语言工程范式本文的脚本路径与源码位置均可作为直接入口英文母版见 docs/guides/I18N.md。【免费下载链接】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），仅供参考