ドキュメントをローカルでビルドする

あなたが読んでいるドキュメントサイトは 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                        # translation-cache パス: .po ファイルの再抽出とマージ
cargo mdbook sync --locale ja            # 1 つのロケールのみ同期する
cargo mdbook sync --force                # すべてを強制的に再翻訳する (品質チェック)
cargo mdbook sync --locale ja --force    # 1 つのロケールのみ強制的に再翻訳する
cargo mdbook stats                       # ロケールごとに翻訳済み/ファジー/未翻訳を表示する
cargo mdbook check                       # .po フォーマットを検証する (翻訳 PR の前に実行)

必ず cargo mdbook … ラッパー経由で実行してください。docs/book/ から直接 mdbook build を実行すると、locales.toml から theme/lang-switcher.js をレンダリングする xtask ステップがスキップされ、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 プリプロセッサを解決できるようにします。

何がどこにビルドされるか

2 つの reference/*.md ファイルは、コード内の実際の clap derive と JSON スキーマから生成されるため、手作業で編集しないでください。代わりに、関連する 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呼び出しもコストも発生しません。