Building the docs locally

The docs site you’re reading is published from docs/book/. You can build the same site on your own machine, useful for offline reading, previewing edits before opening a PR, or developing translations.

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:

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

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

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)

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:

What gets built where

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.

cargo mdbook is an alias for cargo run -p xtask --bin mdbook -- (defined in the cargo config).

For the architecture behind generated references, build-only outputs, gettext extraction, locale fallback, and deployment, see Generated documentation pipeline and Localization catalog lifecycle.

Translations

English is the source language for authored chapters and generated references. Translations live in docs/book/po/<locale>.po files that act as a cache, and cargo mdbook sync keeps them current. Routine English docs PRs do not need to carry the generated .po churn: leave it for a dedicated translation-cache PR. For the full translation pipeline (app strings, docs, zerocode, adding a locale, release passes), see Docs & Translations.

Tips

• Fast iteration on prose: cargo mdbook serve auto-rebuilds on save. Skip cargo mdbook refs unless you’ve changed CLI flags or config schema.
• Fast iteration on translations: edit po/<locale>.po and reload the browser, mdbook serve detects .po changes and rebuilds automatically.
• Cleaning up: rm -rf docs/book/book target/doc removes everything generated.
• Zero-cost re-runs: cargo mdbook sync against unchanged English source completes in seconds, no AI calls, no cost.