文档与翻译

ZeroClaw 拥有两个独立的翻译层：

They are filled separately and stored separately. Both use a provider-agnostic fill pipeline: configure any OpenAI-compatible endpoint in ~/.zeroclaw/config.toml under [providers.models.<type>.<alias>] and pass --provider <type> to the fill commands.

Local models via Ollama are a first-class option — no API keys required, no per-call cost. A hosted provider is also fine for release-grade quality. Translation is a local operation. Run cargo mdbook sync for dedicated translation-cache PRs, release translation passes, and new locales; routine English docs PRs may defer broad generated .po churn to a focused follow-up.

提供程序配置

Ollama 是目前文档的权威来源。请确保已安装 Ollama 并拉取了 qwen3.6:35-a3b 模型。然后，在 ~/.zeroclaw/config.toml（或你已配置的配置目录）中：

# Local via Ollama — free, runs on your machine
[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen3.6:35b-a3b" # Current preferred model

在本地构建文档

在本地构建文档

您正在阅读的文档站点是从 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，无需成本。

填充应用字符串（Fluent）

应用字符串位于 crates/zeroclaw-runtime/locales/ 中。英文是权威来源，并在编译时嵌入。非英文语言环境在运行时从 ~/.zeroclaw/workspace/locales/ 加载。

cargo fluent stats                                          # 每个区域的覆盖率
cargo fluent check                                          # 验证 .ftl 语法
cargo fluent fill --locale ja --provider ollama             # 填充缺失的键（默认批次 50）
cargo fluent fill --locale ja --provider ollama --batch 1   # 逐个处理（当文件包含长条目且在批量处理到第 50 条时被截断时使用，例如 tools.ftl）
cargo fluent fill --locale ja --provider ollama --force     # 重新翻译所有内容
cargo fluent scan                                           # 查找与 Rust 源码相比过期或缺失的密钥

每个批次在下一个 API 调用之前都会写入磁盘，因此中途失败只会丢失当前正在处理的批次。重新运行时，会跳过目标 .ftl 中已存在的键，因此可以自动恢复——无需使用 --force。

填写完毕后，将更新后的 .ftl 文件复制到您的工作区并重新构建，以应用更改：

mkdir -p ~/.zeroclaw/workspace/locales/ja
cp crates/zeroclaw-runtime/locales/ja/cli.ftl ~/.zeroclaw/workspace/locales/ja/cli.ftl

填充文档翻译（gettext）

文档翻译文件位于 docs/book/po/ 目录中。cargo mdbook sync 命令在一个步骤中依次执行提取（extract）、合并（merge）、清除过时条目（strip obsolete）以及 AI 填充（AI-fill）。如果不指定 --provider 参数，sync 仍会执行提取和合并操作，并报告需要翻译的字符串数量——在渲染时，部分翻译的条目会回退使用英文。

cargo mdbook sync --provider ollama              # delta 填充
cargo mdbook sync --provider ollama --force      # 质量检查：重新翻译所有条目
cargo mdbook sync --provider ollama --batch 1    # 逐个处理（对不稳定的本地模型很有帮助）
cargo mdbook sync --locale ja --provider ollama  # 单一语言环境

该流水线具有内置的弹性：

• 泄漏检测 — 如果模型返回的是其自身的指令而非翻译内容，该工具会通过响应长度比例和列表结构来检测这一模式，并尝试从响应的末尾恢复出正确的翻译内容；若恢复失败，则将该条目清空以便重新翻译。
• 增量写入 — 每个批次完成后，.po 文件会被重新写入。如果在运行过程中按 Ctrl-C 中断，不会丢失截至该点的进度。
• 过时的剥离 — msgmerge + msgattrib --no-obsolete 可防止已移除的源字符串作为 #~ 条目不断累积。

Maintainers should accept the routine English docs exception documented in Building the docs locally. Ask for .po updates only when the PR is itself a translation-cache pass, a release translation pass, a new-locale change, or the generated diff is small enough to review.

添加新的区域设置

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

   [[locale]]
   code = "<code>"
   label = "语言名称"
   

2. 翻译应用字符串：

   cargo fluent fill --locale <code> --provider ollama
   

3. 引导并填充文档 .po 文件：

   cargo mdbook sync --locale <code> --provider ollama
   

其他所有内容——lang-switcher.js、CI 部署目标列表、cargo mdbook locales 的输出——都会自动从 locales.toml 中读取。

模型质量说明

翻译质量因语言和模型的不同而有显著差异。

对于发布级别的传递，建议通过 --force 使用托管的前沿模型。在开发过程中进行持续的增量填充时，使用本地的 Ollama 模型即可，且免费。