在本地构建文档

您正在阅读的文档站点是从 docs/book/ 发布的。您可以在自己的机器上构建相同的站点——这对于离线阅读、在提交 PR 之前预览编辑内容或开发翻译非常有用。

一键快速启动

cargo mdbook serve                       # 在 http://localhost:3000/en/ 提供所有语言环境
cargo mdbook serve --locale ja           # 针对日语源码的实时重载
cargo mdbook build                       # 将所有语言环境的静态构建放入 docs/book/book/
cargo mdbook refs                        # 重新生成自动生成的参考页面
cargo mdbook sync                        # translation-cache pass: re-extract + merge .po files
cargo mdbook sync --locale ja            # 仅同步一个区域设置
cargo mdbook sync --force                # 强制重新翻译所有内容（质量检查）
cargo mdbook sync --locale ja --force    # 强制重新翻译某个区域设置
cargo mdbook stats                       # 按语言环境显示已翻译/模糊/未翻译的内容
cargo mdbook check                       # 验证 .po 文件格式（在翻译 PR 之前运行）

必需的工具

cargo mdbook 会快速失败并告知你缺少什么，但作为参考：

构建产物及其位置

这两个 reference/*.md 文件是从代码中实际的 clap 派生宏和 JSON 模式生成的——切勿手动编辑它们。请编辑相关 Rust 类型上的 /// 文档注释。

如何保持翻译的时效性

英文 Markdown 是唯有人类维护的源文件。翻译内容存储在 docs/book/po/<locale>.po 文件中，这些文件充当缓存——而非文档的副本。

当英文源文件发生变化时，cargo mdbook sync 会执行两个阶段：

1. 提取：mdbook-xgettext 会从当前的英文源文件重新生成 po/messages.pot
2. 合并：msgmerge 会更新每个本地化版本的 .po 文件——新增的字符串会带有空的 msgstr ""；已更改的字符串会被标记为 #, fuzzy，并保留旧的翻译作为起点

然后该命令会统计模糊匹配 + 未翻译的条目。如果存在差异且提供了 --provider 参数，fill-translations 工具仅翻译这些条目。未更改的字符串不会产生费用 —— 由于 .po 文件缓存的存在，对未更改的源文件重新运行该操作将是一个空操作（no-op）。

如果不使用 --provider 参数，cargo mdbook sync 仍会执行提取和合并操作，并报告有多少字符串需要翻译。缺少 msgstr 的字符串在渲染时会回退到英文——部分翻译是有效的。

cargo mdbook sync normalizes generated gettext catalogs with stable output rules (msgcat --sort-output --no-wrap --add-location=file). That keeps diffs focused on real source changes and avoids global line-number churn from small edits.

Expected unavoidable churn:

• Header metadata updates (for example POT-Creation-Date / PO-Revision-Date)
• Reference updates when a string moves to a different source file
• Actual source-string additions, removals, and edits

Quick stability check after a small docs edit:

cargo mdbook sync
git diff --numstat -- docs/book/po

Routine English docs PRs do not need to include generated .po churn when the sync output is broad and hard to review. Keep the prose PR focused, leave the generated catalog refresh for a dedicated translation-cache PR, and say so in the PR body:

Skipped committing generated .po updates: this is an English docs-only change, and cargo mdbook sync would produce broad gettext catalog churn. Translation-cache updates are deferred to a dedicated follow-up PR.

Include .po updates only when one of these is true:

• The PR is specifically a translation-cache or release-translation pass.
• The PR adds a new locale.
• cargo mdbook sync produces a small, reviewable diff limited to the strings changed by the PR.

添加新的区域设置

1. 在仓库根目录编辑 locales.toml 文件——这是你唯一需要修改的文件：

   [[locale]]
   code = "xx"
   label = "语言名称"
   

   其他所有内容（lang-switcher.js、CI、cargo fluent fill、cargo mdbook sync）都会自动从此文件读取。

2. 引导并填充文档翻译：

   cargo mdbook sync --locale xx --provider ollama
   

   如果 .po 文件不存在，它会自动引导，然后填充所有条目。

3. 验证并预览：

   cargo mdbook check              # 在格式错误时退出非零状态
   cargo mdbook stats              # 显示覆盖率计数
   cargo mdbook serve --locale xx
   

发布翻译工作流

在标记发布版本之前，请在本地运行完整的翻译流程，并提交更新后的 .po 文件。

# 快速增量传递（仅自上次发布以来新增或更改的字符串）
cargo mdbook sync --provider ollama

# 或者：质量通过 — 重新翻译所有内容
cargo mdbook sync --provider ollama --force

cargo mdbook check   # 提交前验证
cargo mdbook stats   # 审查覆盖率

所使用的模型是 config.toml 中 [providers.models.<name>] 配置项所设置的模型。

提示

• 快速迭代文本内容： cargo mdbook serve 会在保存时自动重新构建。除非你更改了 CLI 标志或配置模式，否则可以跳过 cargo mdbook refs。
• 快速迭代翻译： 编辑 po/<locale>.po 并刷新浏览器——mdbook serve 会检测 .po 文件的更改并自动重新构建。
• 清理： rm -rf docs/book/book target/doc 会删除所有生成的内容。
• 零成本重新运行： 对未更改的英文源执行 cargo mdbook sync 只需几秒即可完成——无需调用 AI，无需成本。