在本地构建文档

您正在阅读的文档站点是从 docs/book/ 发布的。您可以在自己的机器上构建相同的站点，这对于离线阅读、在提交 PR 前预览修改或开发翻译都很有用。

翻译目录（git submodule）

已翻译的 .po 目录位于挂载在 docs/book/po 的 zeroclaw-labs/zeroclaw-docs-translations 子模块中。Rust 开发循环（cargo build, cargo test, cargo clippy）不需要它，但构建或同步文档时需要。初始化一次：

git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw   # 新克隆
git submodule update --init docs/book/po                                   # 现有克隆

如果没有检出子模块，英文仍然可以构建（英文源位于 docs/book/src/），但翻译后的区域会渲染为空。

一键快速启动

cargo mdbook serve                       # 在 http://localhost:3000/en/ 提供所有语言环境
cargo mdbook serve --locale ja           # 针对日语源码的实时重载
cargo mdbook build                       # 将所有语言环境的静态构建放入 docs/book/book/
cargo mdbook refs                        # 重新生成自动生成的参考页面
cargo mdbook sync                        # 翻译缓存流程：重新提取 + 合并 .po 文件
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 … 包装器。直接在 docs/book/ 中运行 mdbook build 会跳过 xtask 步骤，而该步骤负责从 locales.toml 渲染 theme/lang-switcher.js，这会导致构建失败并报错 failed to open theme/lang-switcher.js for hashing。

必需的工具

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

mdbook-mermaid 的版本已固定，但其发布的锁定文件仍选择 mdBook 0.5.0 的预处理器。对该工具不要使用 --locked，以便 Cargo 解析 mdBook 0.5.4 所使用的兼容 0.5.x 预处理器。

构建产物及其位置

这两个 reference/*.md 文件是从代码中实际的 clap 派生和 JSON schema 生成的，请勿手动编辑。应改为编辑相关 Rust 类型上的 /// 文档注释。

cargo mdbook 是 cargo run -p xtask --bin mdbook -- 的别名（在 cargo 配置中定义）。

有关生成引用、仅构建输出、gettext 提取、区域回退和部署背后的架构，请参阅生成文档流水线和本地化目录生命周期。

翻译

英语是编写章节和生成参考文档的源语言。翻译文件位于 docs/book/po/<locale>.po 中，作为缓存使用，cargo mdbook sync 负责保持其最新状态。常规的英语文档 PR 无需附带生成的 .po 变更：将其留给专门的翻译缓存 PR 处理。有关完整的翻译流程（应用字符串、文档、zerocode、添加语言区域、发布流程），请参阅 文档与翻译。

提示

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