跳转至

国际化与机器翻译

文档将英文和简体中文视为经过审阅的规范来源。所有其他已启用语言都是自动生成的 派生产物。语言注册表、来源路由、模型配置和 API 限制均位于 i18n/config.toml。

1. 语言覆盖与来源路由

注册表有意将覆盖范围收敛为 12 种站点语言。其中包含联合国六种官方语言： 阿拉伯语、中文、英语、法语、俄语和西班牙语；东亚地区另外包含日语、韩语与 繁体中文，欧洲地区另外包含德语、意大利语与葡萄牙语。英文和简体中文属于 规范来源，因此共有 10 种语言由机器翻译。

日语、韩语和繁体中文以简体中文为来源；其他所有派生语言均以英文为来源。 每个语言的来源均在配置中明确指定，翻译器不会根据语言名称或文档字符进行猜测。

新增语言时，必须同时更新 i18n/config.toml 和 MkDocs i18n 语言列表。文档 审计会拒绝两个注册表不一致的状态。

2. 规范文档契约

每个 MkDocs 页面都必须同时具有英文文件和 .zh-CN.md 文件。Pull request、 向 main 的推送或手动触发的质量检查如果修改了其中一个规范版本，就必须在 受检查的提交范围内包含另一版本。质量工作流会检查：

  • 规范文档配对以及变更配对；
  • 标题层级与代码围栏的一致性；
  • 本地链接与源码引用；
  • fixture 和测试清单；
  • 所有已配置语言的严格构建。

规范内容可以由人工编写，也可以借助 AI，但必须作为普通源码提交和审阅。 Pull request 工作流绝不会调用翻译 API。

3. 标题编号与片段链接稳定性

Markdown 源文档只保存描述性标题文字，不保存大纲序号。每次 MkDocs 构建时， scripts/mkdocs_heading_numbers.py 会为 H2–H6 添加页面内编号。使用指南页面 的 H2 使用小写字母（a.、b.），更深层级使用字母加十进制（a.1、 a.1.1）；其他页面仍采用十进制页面大纲。左侧使用指南导航则单独使用 1.1 一类层级十进制编号。H1 页面标题与顶层导航栏目不编号。生成序号属于 展示元数据：移动章节会改变可见序号，但不会改变片段标识符。

构建钩子会先固定每个标题的显式标识符，再添加可见序号。 i18n/legacy-heading-anchors.json 保留移除手写序号之前已经发布过的片段别名。 不要随意编辑这份生成的兼容映射，也不要在规范或派生 Markdown 中重新加入手写 大纲序号；文档审计会拒绝这种内容。

4. 派生文档契约

生成页面采用 MkDocs 后缀模式，例如 index.fr.md 或 guide/configuration.ja.md。每个页面都包含确定性的 front matter，记录：

  • 规范来源语言和路径；
  • 来源文件的 SHA-256 摘要；
  • 实际使用的模型与提示词版本；
  • 该页面属于机器翻译。

i18n/manifest.json 还会记录输出摘要和翻译输入指纹。当来源、术语表、提示词、 模型或生成输出发生变化时，页面即被视为过期。除非明确要求完整重建，翻译器只 请求过期单元。

翻译后的标题保留本地化的自然 slug，同时获得规范来源 slug 的隐藏别名。由于 Markdown 链接目标在其他情况下会受到保护、不允许模型修改，这些别名可以保证 同页和跨页片段链接在每种语言中都有效。别名可以离线刷新，无需再次调用翻译 API。

生成文件不得手工编辑。主分支翻译工作流会重新生成这些文件，并在每种语言完成后 把该语言作为一个批次提交到由质量检查精确 SHA 派生的 generated-only 分支。 后续运行会先验证再复用该分支，因此中断时只会丢失仍在处理的那一种语言。工作流 完成派生语言审计、完整测试套件与所有语言的严格构建之前，main 保持不变。 验证全部通过后，工作流再次确认 main 未前进，再用一次 fast-forward 推送提升 checkpoint，并部署同一份已经验证的站点制品。

5. Markdown 保护与提示词契约

发送 API 请求前，翻译器会把 front matter、围栏代码、行内代码、链接目标、 HTML 标签和裸 URL 替换为不可变占位符。任何占位符缺失、重复、凭空出现或无法 按契约还原，响应都会被拒绝。

提示词还要求标题层级和代码围栏语言保持一致。实现会在恢复受保护内容后独立验证 这些属性。翻译输出必须是 JSON 对象；JSON 外的说明文字、空内容、异常结束原因 或不兼容的数据结构都属于失败。

Markdown 与导航目录提示词在 i18n/prompts/ 中单独版本化； i18n/glossary.json 保存稳定的产品名和命令术语。

6. 模型配置与凭据

默认模型配置为 deepseek-v4-flash。实现不会针对该名称编写条件分支。以后更换 模型时，只需修改 i18n/config.toml、传入 --model，或设置 DEEPSEEK_TRANSLATION_MODEL 工作流变量。最终解析出的模型会记录在每个生成 页面和 manifest 条目中。

GitHub Actions 只从名为 DEEKSEEK_API_KEY 的 repository secret 读取 API 凭据。只有离线计划显示存在待处理的 API 翻译单元时，生成步骤才会获得该 secret；不可信的 pull request 代码以及无需 API 的规划、清理和验证步骤均无法 获得。认证值绝不会写入日志、生成文件、artifact 或 manifest。

7. 页面提示与语言偏好

机器生成页面会在渲染时获得本地化警告。该警告说明页面由 AI 翻译，链接到权威的 英文或简体中文原文，并链接到预填内容的翻译问题报告。提示不属于翻译后的 Markdown，也不会生成目录条目。

访问者首次打开站点根页面时，网站会把 navigator.languages 与已经配置的语言 备选项进行比较，并在存在兼容项时选择对应语言。用户手动选择的语言会保存在 本地，并在以后访问时优先生效。

8. 维护命令

在不发起网络请求的情况下查看待翻译单元数量：

uv run python scripts/translate_docs.py --plan

验证所有生成页面和目录翻译均为最新状态：

uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required

在不调用 API 的情况下刷新稳定的来源标题别名：

uv run python scripts/translate_docs.py --refresh-heading-anchors

使用明确模型强制完整重建：

DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
  --force --model deepseek-v4-flash

自动工作流会使用 repository secret，而不是把密钥放在命令行中。