企业官网建设流程全解析

OmniRoute 多语言国际化(i18n)工具链：翻译流水线、校验门禁与 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 的 i18n 体系覆盖仪表盘 UI 字符串、文档多语镜像与 RTL（阿拉伯语/希伯来语）布局三大面。本篇基于仓库中的 i18n 指南文档，深入讲解其"单一事实源 + next-intl 运行时解析 + 自动翻译引擎 + 多层校验门禁"的完整工具链，读完后可独立掌握新增语言、批量翻译、翻译质量校验与 CI 集成的全套实操命令，并能对照源码理解 locale 解析回退与占位符保护的底层实现。

该文档位于 docs/i18n/phi/docs/guides/I18N.md，是 docs/guides/I18N.md（英文原版）随文档翻译流水线生成的菲律宾语（Filipino）镜像，两者内容同源。本文以该文档骨架为主体，并对照当前仓库源码补充实现证据。

1. 快速参考：i18n 常用命令总览

文档给出的命令速查表（覆盖翻译生成、校验、QA 全流程）：

说明：原文档快照时期脚本位于scripts/顶层；当前仓库中这些脚本已统一收纳至 scripts/i18n/ 目录（如 validate_translation.py、check_translations.py、i18n_autotranslate.py），上表已按当前仓库实际路径给出。此外当前仓库的 package.json 还注册了更推荐的 npm 脚本别名，如i18n:run（增量 LLM 文档翻译）、i18n:check（漂移检测门禁）、i18n:sync-ui（UI 键同步）、i18n:add-locale（一键新增语言），详见第 4 节。

2. 架构

2.1 单一事实源（Source of Truth）

文档声明的核心资产：

• UI 字符串：src/i18n/messages/en.json（英文源，约 2800 个键）
• 语言文件：src/i18n/messages/{locale}.json（各语言翻译）
• 框架：next-intl，基于 Cookie 的 locale 解析
• 配置：src/i18n/config.ts — 定义全部 locale、语言名与国旗

从源码结构看，当前仓库的"声明层"已进一步收敛：src/i18n/config.ts 开头注释明确config/i18n.json才是 SOURCE OF TRUTH（同时被文档翻译流水线消费），config.ts只是"thin typed adapter"（薄类型适配器），禁止在其中手工维护语言清单。它从 config/i18n.json 读取并导出LOCALES、LANGUAGES、RTL_LOCALES、LOCALE_ALIASES与LOCALE_COOKIE = "NEXT_LOCALE"（见 src/i18n/config.ts）。文档快照时期配置仍在config.ts内直接定义 30 个 locale；当前仓库语言数量已显著扩展（英文原版指南现声明支持 51 种语言）。

2.2 运行时流程（Runtime Flow）

文档描述的 4 步运行时链路：

1. 用户选择语言 → 写入NEXT_LOCALECookie；
2. src/i18n/request.ts 解析 locale：Cookie →Accept-Language/请求头 → 回退en；
3. 动态import加载messages/{locale}.json；
4. 组件使用useTranslations("namespace")与t("key")。

request.ts 的实现与文档一致且有更完整的细节：getRequestConfig先读NEXT_LOCALECookie（第 125 行），缺失时读x-locale请求头（第 129 行），再经resolveRequestedLocale(locale, LOCALES, LOCALE_ALIASES, DEFAULT_LOCALE)完成别名归一化（第 132 行），随后动态导入对应语言的 JSON 消息文件（第 135 行）。源码还实现了三层容错机制：

• 键级深合并回退：deepMergeFallback（request.ts）逐键将英文源合并进本地化文件，且对__proto__/constructor/prototype等键做了原型污染防护；
• __MISSING__:未翻译哨兵：request.ts 导出PLACEHOLDER_PREFIX = "__MISSING__:"，当本地化文件中某键被同步脚本回填为该哨兵值时，深合并会视其为"不存在"，让干净的英文值胜出（对应 issue #7258）；
• 命名空间级浅合并（request.ts）：当本地化文件缺少新命名空间（如新增的cliCode、acpAgents等）时，按顶层命名空间整体回退到英文，保证新功能在翻译补齐前仍可显示。

2.3 支持的语言

文档快照列出 30 个 locale（当前仓库已扩展，下表为文档原始清单，phi即本文档所属的菲律宾语，其 Google Translate 代码为tl）：

RTL 处理在生成器中也有对应定义：generate-multilang.mjs 中RTL_LOCALES = new Set(["ar", "fa", "he", "ur"])，即 RTL 集合会随新语言（如fa、ur）的加入而同步扩展。

3. 新增一种语言的完整步骤

文档给出的 6 步流程

第 1 步：注册 Locale。文档当时的做法是编辑 src/i18n/config.ts：

// Add to LOCALES array "xx", // Add to LANGUAGES array { code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },

第 2 步：加入生成器。编辑 scripts/i18n/generate-multilang.mjs 的LOCALE_SPECS数组，追加一条规格：

{ code: "xx", googleTl: "xx", label: "XX", flag: "🏳️", languageName: "Language Name", readmeName: "Language Name", docsName: "Language Name", },

该LOCALE_SPECS在源码中可完整看到（generate-multilang.mjs），每个条目携带code、googleTl（Google 侧语言码，如he对应iw）、label、flag等字段，分别服务于 UI 目录命名、翻译 API 调用与 README/文档镜像标题。

第 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

当前仓库的推荐做法：一键 add-locale

从源码结构看，上述 6 步的手工流程已被 scripts/i18n/add-locale.mjs 自动化：一条命令即可把新 locale 落到所有表面（config、国旗、仪表盘目录、文档镜像、CLI 目录、README 与索引、语言条，可选站点）。结合英文原版指南（docs/guides/I18N.md）中的用法：

# 需要 .env 中配置 OMNIROUTE_TRANSLATION_API_URL / _API_KEY / _MODEL node scripts/i18n/add-locale.mjs --code=el --english=Greek --native=Ελληνικά --flag=🇬🇷 # 预览模式： node scripts/i18n/add-locale.mjs --code=el --english=Greek --native=Ελληνικά --flag=🇬🇷 --dry-run

新增后需通过的语言面一致性校验包括i18n:check-ui-coverage、i18n:check-ratio（真实翻译比例棘轮）、check:docs-all与check:cli-i18n。对应 package.json 脚本为"i18n:add-locale": "node scripts/i18n/add-locale.mjs"。

4. 自动翻译流水线

4.1 generate-multilang.mjs（Google Translate 引擎）

文档将其定位为主自动翻译引擎，用于 UI 字符串、README 与文档。用法：

node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]

文档列出的关键特性，均可在 generate-multilang.mjs 源码中逐一印证：

• 文本保护：翻译前对代码块（```）、行内代码、Markdown 链接/图片（text）、HTML 标签、表格与 ICU 占位符（{count}、{value}、{total}等）做掩码，翻译后再还原——这是防止翻译 API 破坏技术内容的关键设计；
• 分块批处理：用__OMNIROUTE_I18N_SEPARATOR__分隔符把多条字符串拼成一次请求以最小化 API 调用，源码常量URL_MAX_TEXT_LENGTH = 1800限定了单请求最大 1800 字符（generate-multilang.mjs）；
• 内存缓存：TRANSLATION_CACHE = new Map()避免同一会话内重复字符串的冗余调用；
• 重试逻辑：针对 429/5xx 采用指数退避（最多 5 次，300ms × 次数）；
• 超时：REQUEST_TIMEOUT_MS = 20000，每请求 20 秒；
• 跳过已存在文件：目标文件已存在时不覆盖，保证人工修订不被自动翻译冲掉。

重要行为（文档特别强调）：

• docs/i18n/README.md每次运行重新生成——它是全部文档的自动索引；
• 根目录README.{code}.md仅在不存在时创建（源码中EXISTING_README_CODES集合包含pt-BR、es、fr、it、ru、zh-CN、zh-TW、de等已有变体）；
• 所有翻译文档中的语言条（🌐 **Languages:** ...）会被自动插入/更新——本文档第 3 行那串多语导航链接即由该机制维护。

现状提示：当前源码文件头部已标注DEPRECATED 2026-05-13（generate-multilang.mjs）——docs模式已被基于 LLM 的run-translation.mjs取代并将于 v3.10 移除；messages与readme模式因尚无替代而保留。

4.2 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/中的英文段落；跳过代码块、表格与已翻译内容；以技术翻译系统提示词发送段落给 LLM；支持全部语言。

4.3 当前推荐路径：基于哈希的增量 LLM 翻译流水线

从源码结构看（scripts/i18n/run-translation.mjs、scripts/i18n/check-translation-drift.mjs），仓库现主推的文档翻译路径是 package.json 中注册的 npm 脚本：

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:check # CI 门禁：状态漂移则非零退出

配套机制：后端由环境变量配置（OMNIROUTE_TRANSLATION_API_URL/OMNIROUTE_TRANSLATION_API_KEY/OMNIROUTE_TRANSLATION_MODEL，可选项OMNIROUTE_TRANSLATION_TIMEOUT_MS默认 60000、OMNIROUTE_TRANSLATION_CONCURRENCY默认 4，写在.env中、绝不入库）；状态文件.i18n-state.json（提交入库）按"源文件 × locale"记录 SHA-256 哈希，漂移检测完全确定性、不发 API 调用。UI 字符串的对应替代命令为npm run i18n:sync-ui -- --translate-markers --batch-size=40。

5. 校验与 QA

5.1 validate_translation.py（翻译校验器）

把任意 locale 的 JSON 与en.json对比并报告问题（scripts/i18n/validate_translation.py，约 635 行）：

# 快速检查（仅计数） 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）：en.json有而 locale 文件没有；
• 多余键（Extra）：locale 文件有而en.json没有；
• 未翻译键（Untranslated）：locale 值与英文源相同（白名单除外）；
• 占位符失配：源与译文之间 ICU 占位符不一致。

退出码（供 CI 区分严重程度）：

语言选择：环境变量TRANSLATION_LANG=cs或-l cs参数；源码 validate_translation.py 中get_target_lang()的优先级为环境变量 → CLI 参数 → 默认cs（向后兼容）。

5.2 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 # 自动修复（把缺失键补进 en.json） python3 scripts/i18n/check_translations.py --fix

它与validate_translation.py互补：后者保证"翻译文件之间"的键一致，前者保证"代码引用与 en.json"之间不脱节。

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

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

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

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

5.4 run-visual-qa.mjs（Playwright 视觉 QA）

在多种 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 报告。

5.5 术语表一致性层（仓库补充）

从源码结构看，仓库在键对等与 ICU 校验之外还维护了一层术语表门禁：scripts/i18n/glossary/ 下按 locale 存放反复出现概念（provider、connection、routing、fallback、quota 等）的canonical译法与synonyms列表，捕获"同一英文概念在不同字符串里被译成两个同样合法但互相冲突的词"这类语义漂移；protected-terms.json则强制产品/协议/环境变量名（OmniRoute、OAuth、MCP、DATA_DIR等）在译文值中原样出现。运行入口为 check-glossary-consistency.mjs（npm run i18n:check-glossary，支持--locale/--json/--report参数）。此外npm run i18n:check-ratio（check-translation-ratio.mjs）以"与英文相同值/占位符比例"作为真实翻译程度的棘轮指标。

6. 管理不可翻译键（untranslatable-keys.json）

文件：scripts/i18n/untranslatable-keys.json

白名单形式，声明"应保持与英文源完全一致"的键，供validate_translation.py避免对它们误报"未翻译"。结构如下：

{ "description": "Keys that should remain untranslated...", "keys": [ "common.model", "common.oauth", "health.cpu", ... ] }

源码中加载逻辑位于 validate_translation.py：启动时从外部 JSON 读取keys数组装入UNTRANSLATABLE_KEYS集合，文件缺失时降级为空集。

应放入白名单的内容类别（文档归纳）：

• 品牌/产品名：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数组后重跑校验即可。注意它与术语表的protected-terms.json粒度不同：前者按键路径把整键排除出对等/ICU 检查；后者按概念检查任何译文值内部是否篡改了受保护名词。

7. CI 集成

CI 流水线中的 i18n 门禁

文档描述的 CI 设计（.github/workflows/ci.yml）为三个协作的 job：

1. i18n-matrixjob— 动态发现所有 locale 文件（排除en.json）；
2. i18njob— 对每个 locale 并行执行validate_translation.py quick -l '<lang>'；
3. ci-summaryjob— 把结果聚合成仪表盘摘要。

# i18n-matrix: 发现语言 LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$') # i18n: 逐语言校验 python3 scripts/i18n/validate_translation.py quick -l '${{ matrix.lang }}'

在当前的 ci.yml 中，逐 locale 的validate_translation.py quick调用（ci.yml）与术语表门禁 jobi18n-glossary-zhcn（ci.yml）均已确认存在；摘要表会输出"Languages checked / Total untranslated"等指标，形如：

## 🌍 Translations | Metric | Value | |--------|------| | Languages checked | 30 | | Total untranslated | 0 | ✅ All translations complete

8. 文件结构

文档给出的目录全景（按当前仓库实际布局整理，脚本统一位于scripts/i18n/下）：

src/i18n/ ├── config.ts # Locale 定义（薄适配器，读 config/i18n.json） ├── request.ts # 运行时 locale 解析 + 三级回退合并 └── messages/ ├── en.json # 事实源（约 2800 键） ├── cs.json # 捷克语翻译 ├── de.json # 德语翻译 └── ... # 全部 locale 文件 config/ └── i18n.json # 唯一 locale 声明处（UI + 文档 + RTL + 别名） scripts/i18n/ ├── generate-multilang.mjs # 自动翻译引擎（Google Translate，已标记弃用） ├── run-translation.mjs # 增量哈希 LLM 翻译（当前主推） ├── i18n_autotranslate.py # LLM 文档翻译器 ├── add-locale.mjs # 一键新增语言 ├── validate_translation.py # 翻译校验器 ├── check_translations.py # 代码-JSON 键校验器 ├── check-translation-drift.mjs # 漂移检测（i18n:check） ├── check-translation-ratio.mjs # 真实翻译比例棘轮 ├── check-glossary-consistency.mjs # 术语表一致性 ├── generate-qa-checklist.mjs # 静态分析 QA ├── run-visual-qa.mjs # Playwright 视觉 QA ├── glossary/ # 分语言术语表 └── untranslatable-keys.json # 不可翻译键白名单 .github/workflows/ └── ci.yml # i18n 校验矩阵 + 术语表门禁 docs/ ├── guides/I18N.md # 英文原版 i18n 指南（手写、持久） ├── i18n/ │ ├── README.md # 语言索引 │ ├── phi/ │ │ └── docs/guides/I18N.md # 本文件：菲律宾语翻译镜像 │ ├── cs/、de/ ... # 各语言文档目录 └── reports/ ├── i18n-qa-checklist-*.md # 静态分析报告 └── i18n-visual-qa-*.md # 视觉 QA 报告

9. 最佳实践

编辑翻译时的工作流

1. 永远先编辑en.json—— 它是事实源；
2. 运行翻译同步把新键传播到所有 locale（文档时期为generate-multilang.mjs messages，当前为npm run i18n:sync-ui）；
3. 审校自动译文—— 机器翻译只是起点而非终稿；
4. 提交前校验——python3 scripts/i18n/validate_translation.py quick -l <lang>；
5. 需要整键保留英文时，更新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/i18n/check_translations.py --verbose

RTL 注意事项

• 阿拉伯语（ar）与希伯来语（he）是 RTL locale（当前 RTL 集合已扩展至ar、fa、he、ur）；
• 避免硬编码left/rightCSS —— 使用start/end逻辑属性；
• 视觉 QA（run-visual-qa.mjs）会捕获 RTL 布局错位。

10. 已知问题与历史

in.json→hi.json修复。生成器早期误用code: "in"（Google Translate 的已弃用代码）表示印地语而非正确的 ISO 639-1hi，导致产生与hi.json重复的孤儿文件in.json。修复方式是把LOCALE_SPECS中code: "in"改为code: "hi"并删除孤儿文件（该问题由上游提交952b0b22c引入）。后续in又曾以"Indonesian (Legacy)"身份长期存在，最终从所有表面移除，id现声明"aliases": ["in"]，使旧的NEXT_LOCALE=in或OMNIROUTE_LANG=in解析到id——别名机制正由 config/i18n.json 的aliases字段驱动、经 src/i18n/config.ts 导出为LOCALE_ALIASES。

docs/i18n/README.md曾为纯自动生成。文档快照时期，该索引每次运行generate-multilang.mjs docs全量重生成，手工编辑会丢失，手写内容应放在docs/guides/I18N.md。从源码演进看，当前它已改为手工维护：add-locale.mjs只做行内插入新 locale 行与更新计数句，双向一致性由单测tests/unit/i18n-locale-surfaces-parity.test.ts守护（配置了文档 locale 就必须有索引行，索引行必须能映射回已配置 locale）。

不可翻译键白名单外置。untranslatable-keys.json白名单从validate_translation.py内的内联 Python 集合迁移为外部 JSON 文件以便维护，校验器运行时加载（源码 validate_translation.py 可确认）。

quick 检查的 Ignored 计数。quick模式现会输出被untranslatable-keys.json忽略的键数量，让"未翻译"计数与"有意不译"计数分离、互不干扰：

Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236

11. 小结

OmniRoute 的 i18n 工具链呈现清晰的四层结构：声明层（config/i18n.json→src/i18n/config.ts薄适配器）、运行时层（next-intl+ Cookie 解析 + 键级/哨兵/命名空间三级回退合并，见 src/i18n/request.ts）、生产层（Google Translate 批量引擎与 LLM 增量引擎双轨，文本掩码、分块批处理与哈希状态保证可重复性）、质量层（键对等校验、占位符检测、术语表一致性、静态/视觉 QA 与 CI 矩阵门禁）。对维护者而言，最重要的纪律是：先改en.json、同步后必校验、占位符零容忍、整键保留英文走白名单——这套规则由前述脚本与 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, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute