企业官网建设流程全解析

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, RTK+Caveman 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/根目录）：

架构：单一事实源与运行时 locale 解析

单一事实源（Source of Truth）

OmniRoute 的 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 locale；docs/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 为准）：

1. 用户在界面选择语言 → 写入NEXT_LOCALECookie（LOCALE_COOKIE = "NEXT_LOCALE"，定义于 src/i18n/config.ts）；
2. src/i18n/request.ts 的getRequestConfig依次解析 locale：Cookie →x-locale请求头 → 兜底en（src/i18n/request.ts）。这里比旧版文档描述的"Accept-Language 头"更进一步：文档管线与 CLI 侧也镜像了同一套解析逻辑；
3. src/i18n/resolveRequestedLocale.ts 做 locale 归一化：先精确匹配，再大小写不敏感匹配，最后查LOCALE_ALIASES别名表（例如遗留 Cookie 中的in→id、uk→uk-UA、fil/tl→phi、zh-hant→zh-TW），都匹配不上则回退默认en（src/i18n/resolveRequestedLocale.ts）；
4. 动态import('./messages/${locale}.json')加载该语言消息树（src/i18n/request.ts）；
5. 双层英文兜底（src/i18n/request.ts）：
   • deepMergeFallback：逐键深合并en.json，只补齐 locale 文件中缺失的键，locale 已有值优先。同时会跳过__proto__/constructor/prototype键以防原型污染；
   • __MISSING__:哨兵：i18n 同步脚本回填未翻译键时会写入__MISSING__:<英文值>前缀（src/i18n/request.ts），合并时该值被视为"缺失"，让干净的英文兜底值生效；
   • 命名空间级浅合并：locale 文件中整个缺失的顶层命名空间（例如新增的cliCode、acpAgents）直接保留英文版本，保证新命名空间在未翻译时不会报错而是显示英文；
6. 组件侧使用useTranslations("namespace")+t("key")取文案。

受支持的 Locale（当前 51 个）

以下表格整理自 config/i18n.json；id行同时标注了 Google Translate 遗留代码问题（见文末"已知问题"）。RTL 语言共 4 个：ar、fa、he、ur。

别名（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）。仓库中已有完整先例：例如hi（Hindi）条目为code: "hi", googleTl: "hi"，uk-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 xx

6. 生成翻译文档

旧方式为node scripts/i18n/generate-multilang.mjs docs；当前推荐切换到 v3.8.0 的哈希增量 LLM 管线（见下节）：

npm run i18n:run # 增量翻译所有文档 npm run i18n:run -- --locale=xx # 只翻译指定语言

自动翻译管线

generate-multilang.mjs（Google Translate 引擎）

这是主力自动翻译引擎——基于 Google Translate 免费 API，为 UI 字符串（src/i18n/messages/*.json）与根目录 README 变体（README.{code}.md）生成翻译：

node scripts/i18n/generate-multilang.mjs [messages|readme|docs|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.mjs（npm run i18n:sync-bars）专门维护这些语言条。

注意：该脚本头部已标注DEPRECATED 2026-05-13——docs模式被新的 LLM 管线取代（计划 v3.10 移除），messages与readme模式目前仍由它承担。日常文档翻译请优先使用下文npm run i18n:run。

i18n_autotranslate.py（LLM 引擎）

次级翻译器——调用任意 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+ 仓库内英文 Markdown（CLAUDE.md、GEMINI.md、README.md、docs/*.md等），产物镜像写入docs/i18n/<locale>/...（带 H1 头 + 语言条 +---分隔符）。状态文件.i18n-state.json（已提交进仓库）记录每个源文件与每个产物目标的哈希，重跑时只翻译源哈希变化或目标缺失的文件——漂移检测是自动且确定性的，不需要额外 API 调用。

npm run i18n:run # 增量翻译（只动变化的源） npm run i18n:run -- --locale=pt-BR # 限定一个语言 npm run i18n:run -- --files=CLAUDE.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，不提交）：

package.json中还有一组翻译一致性检查脚本（npm run前缀）：i18n:check（漂移）、i18n:sync-ui（sync-ui-keys.mjs，即写入__MISSING__:哨兵的同步器）、i18n:check-ui-coverage、i18n:check-value-drift、i18n:check-glossary（术语一致性，配合 scripts/i18n/glossary 与 glossary-normalize.mjs）、i18n:check-ratio。

翻译校验与 QA

validate_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 keys：en.json有而 locale 文件没有的键（硬错误）；
• Extra keys：locale 文件有而en.json没有的键；
• Untranslated keys：译文值与英文源完全相同的键（白名单除外，软警告）；
• Placeholder mismatches：源与译文之间 ICU 占位符不一致。

退出码约定：

语言可通过环境变量TRANSLATION_LANG=cs或-l cs参数指定。

check_translations.py（代码—JSON 键核对器）

扫描src/**/*.tsx与src/**/*.ts中的useTranslations()调用，核对所有被引用的键是否存在于en.json（scripts/i18n/check_translations.py）：

python3 scripts/i18n/check_translations.py # 基础检查 python3 scripts/i18n/check_translations.py --verbose # 详细输出 python3 scripts/i18n/check_translations.py --fix # 自动把缺失键补进 en.json

generate-qa-checklist.mjs（静态分析 QA）

扫描 Next.js 页面文件中的 i18n 风险指标并生成 Markdown 报告（scripts/i18n/generate-qa-checklist.mjs）：

node scripts/i18n/generate-qa-checklist.mjs

检查项：固定宽度 class 滥用（文本溢出风险）、方向性 left/right class（RTL 风险）、易裁切模式、locale 键齐平度（与en.json相比的缺失/多余键）、优先语言（es、fr、de、ja、ar）README 语言选择条。输出到docs/reports/i18n-qa-checklist-{date}.md。

run-visual-qa.mjs（Playwright 视觉 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_URL=http://staging.example.com QA_LOCALES=de,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.ai；
• ICU/格式化字符串：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 任务"演进为路径分流模式：

1. 变更分类：changes步骤基于git diff将变更分为code/i18n/workflow等类别，纯docs/i18n变更走专用 i18n 任务，不会触发昂贵的代码回归任务；
2. per-locale 校验：对每个 locale 运行validate_translation.py quick -l '<lang>'；
3. 一致性门禁（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 报告

最佳实践

编辑翻译时

1. 永远先改en.json——它是事实源；
2. 运行翻译生成器把新键传播到各语言（UI 用generate-multilang.mjs messages，文档用npm run i18n:run）；
3. 复核自动翻译——机器翻译是起点而非终稿；
4. 提交前校验：python3 scripts/i18n/validate_translation.py quick -l <lang>；
5. 若某键应保持英文，把它加入untranslatable-keys.json。

占位符安全（Placeholder Safety）

• ICU 占位符（{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 --verbose

RTL 注意事项

• 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute