Docs Build Commands - Zeroclaw

Translation catalogues (git submodule)

The translated .po catalogues live in the zeroclaw-labs/zeroclaw-docs-translations submodule mounted at docs/book/po. The Rust dev loop (cargo build, cargo test, cargo clippy) does not need it, but building or syncing the docs does. Initialise it once:

sh

git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw   # fresh clone
git submodule update --init docs/book/po                                   # existing clone

</div>

Without the submodule checked out, English still builds (the English source lives in docs/book/src/), but translated locales render as empty.

One-command quickstart

sh

cargo mdbook serve                       # serve all locales at http://localhost:3000/en/
cargo mdbook serve --locale ja           # live-reload against Japanese source
cargo mdbook build                       # static build of every locale into docs/book/book/
cargo mdbook refs                        # regenerate the auto-generated reference pages
cargo mdbook sync                        # translation-cache pass: re-extract + merge .po files
cargo mdbook sync --locale ja            # sync one locale only
cargo mdbook sync --force                # force-retranslate everything (quality pass)
cargo mdbook sync --locale ja --force    # force-retranslate one locale
cargo mdbook stats                       # show translated/fuzzy/untranslated per locale
cargo mdbook check                       # validate .po format (run before a translation PR)

</div>

Always go through the cargo mdbook … wrapper. Running mdbook build directly from docs/book/ skips the xtask step that renders theme/lang-switcher.js from locales.toml, which fails the build with failed to open theme/lang-switcher.js for hashing.

Required tools

cargo mdbook will fail fast and tell you what's missing, but for reference:

Tool	Install
`mdbook`	`cargo install mdbook --locked`
`mdbook-i18n-helpers`	`cargo install mdbook-i18n-helpers --locked`
`cargo`	https://rustup.rs
`gettext` (msgfmt, msgmerge)	`apt install gettext` / `brew install gettext`

What gets built where

Source	Output	Generated by
`docs/book/src/*/.md` (hand-written)	`docs/book/book/<locale>/`	`mdbook build`
`docs/book/src/reference/cli.md`	(same path; gitignored)	`cargo mdbook refs`
`docs/book/src/reference/config.md`	(same path; gitignored)	`cargo mdbook refs`
`target/doc/` (rustdoc)	`docs/book/book/api/`	`cargo doc --no-deps --workspace`

The two reference/*.md files are generated from the actual clap derives and JSON schema in the code, never edit them by hand. Edit the /// doc comments on the relevant Rust types instead.