ドキュメントと翻訳

ZeroClawには2つの独立した翻訳レイヤーがあります：

これらの手順を支える正本、保存、読み込み、フォールバック、リリースの境界については、ローカライズカタログのライフサイクルを参照してください。ドキュメント抽出の入力となる生成済み英語リファレンスは、生成ドキュメントパイプラインにマッピングされています。

それらは個別に埋められ、個別に保存されます。どちらも共有のプロバイダー非依存ランタイムパスを使用します。providers.models.<kind>.<alias> 配下にモデルプロバイダーを設定し、fill コマンドに --model-provider <alias> を渡します。設定済みの任意のエイリアスを選択できます。同一のエイリアスが複数の kind 配下に存在する場合は、単独のエイリアス（--model-provider <alias>）、または kind.alias 修飾子（--model-provider anthropic.<alias>）を指定できます。リゾルバーは、一致したエントリにモデル名が指定されていることを要求し、その後、エンドポイントのデフォルト値、認証、ワイヤプロトコル、および任意のカスタム uri 処理をランタイムプロバイダースタックに委譲します。

Ollama を使ったローカルモデルは第一級の選択肢です。API キーは不要で、呼び出しごとのコストもかかりません。リリース品質を求める場合は、ホスト型プロバイダーでも構いません。翻訳はローカルでの操作です。専用の翻訳キャッシュ PR、リリース時の翻訳パス、新しいロケールの追加には cargo mdbook sync を実行してください。通常の英語ドキュメントの PR では、生成される .po ファイルの広範な変更を、専用のフォローアップに後回しにしても構いません。

プロバイダー設定

Ollama は現在ドキュメントの標準的なソースです。Ollama がインストールされ、qwen3:30b-a3b がプルされていることを確認し、Ollama プロバイダーエントリを設定してください。uri はエンドポイントの完全な URL で、オプションです。設定しないままにすると、プロバイダーファミリーのデフォルトエンドポイント（ランタイムプロバイダースタックによって解決される）が使用されます。セルフホストのゲートウェイやプロキシを指す場合にのみ設定してください。設定済みのファミリーであれば何でも動作します（Anthropic、OpenAI、OpenRouter、Ollama、…）。翻訳ツールが実際のランタイムプロバイダーを構築するため、各ファミリーのエンドポイント、認証ヘッダー、ワイヤープロトコルは自動的に処理されます。OpenAI 互換性の要件はありません。

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

翻訳カタログ (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 の設定で定義）のエイリアスです。このセクションのコントリビューター向けの簡潔なバージョンについては、ドキュメントをローカルでビルドするを参照してください。

[!NOTE] 全文検索は主要ロケール（英語、locales.tomlの最初）に対してのみ構築されます。翻訳されたロケールは、検索インデックスや検索ボックスなしでビルドされます。ロケールごとの検索インデックスは大きく（それぞれ約6～7 MB）、gh-pagesのクローンサイズの大半を占めます。検索を英語に限定することで、クローンを軽量に保てます。翻訳されたロケールに検索ボックスを戻すには、build_locales（xtask/src/cmd/mdbook/build.rs）でそのビルドのoutput.html.search.enableを再度有効にする必要があります。

翻訳を最新に保つ方法

英語のソースが変更されると、cargo mdbook sync は2つのステージを実行します。

1. 抽出: mdbook-xgettext は現在の英語ソースから po/messages.pot を再生成します。
2. マージ: msgmerge --no-fuzzy-matching は各ロケールの .po ファイルを更新し、新規または変更された原文文字列に空の msgstr "" を設定して、廃止されたエントリを削除します。マージ前から存在していた fuzzy エントリだけが、後でレビューしたり、入力を受け入れたりするために利用可能な状態で残ります。

次にコマンドはあいまい (fuzzy) + 未翻訳のエントリを数え、--model-provider が指定されている場合はそれらのみを補完します。変更されていない文字列にはコストがかかりません。.po キャッシュにより、変更されていないソースに対して再実行しても何も行われません。--model-provider を指定しない場合でも、sync は抽出 + マージを実行して差分を報告します。msgstr のない文字列は、レンダリング時に英語にフォールバックします。

Sync は安定した出力ルール（msgcat --sort-output --no-wrap --add-location=file）でカタログを正規化するため、差分は実際のソース変更に集中したままになります。避けられない変更点：ヘッダーのメタデータ（POT-Creation-Date など）、文字列が別ファイルに移動した際の参照位置の更新、そして実際のソース文字列の編集です。

通常の英語ドキュメントのPRでは、広範囲にわたる .po の変更を、それに特化したフォローアップに先送りしても構いません。.po の更新を含めるのは、PRが翻訳キャッシュの更新作業、リリース翻訳の更新作業、ロケールの追加、またはレビュー可能な小さな差分を生成する場合のみにしてください。

アプリの文字列を埋め込む（Fluent）

アプリの文字列は crates/zeroclaw-runtime/locales/ にあります。英語がソースとして扱われ、コンパイル時に埋め込まれます。

ランタイムの読み込み境界。

• 埋め込みソース: 英語の cli.ftl と tools.ftl が埋め込まれています。builtin_cli_ftl_source() はランタイムによって埋め込まれた非英語の CLI カタログを列挙します。zeroclaw-tools はクレートの依存関係の方向を維持するため、英語のツール文字列を別途埋め込みます。
• ディスクオーバーレイ: <config-dir>/data/ftl/<locale>/ にあるカタログは、埋め込まれた CLI 値を上書きし、翻訳されたランタイム/ツール値を提供します。zeroclaw locales fetch はこの共有ディレクトリにデータを設定します。
• 利用に関する注意: .ftl ファイルを埋めてコミットすると、追跡対象のカタログソースが更新されますが、コンシューマーがそれを利用するのは、そのローダーがカタログを埋め込んでいる場合、またはそのローダーが読み取る場所にファイルがインストールされている場合に限られます。

apps/zerocode TUIは独立したFluentカタログ（apps/zerocode/locales/）を管理しています。以下のzerocode stringsを参照してください。cargo fluentは両方のカタログルート（ランタイム＋zerocode）を走査するため、以下の各サブコマンドはデフォルトで両方を対象とします。

cargo fluent stats                                                   # ロケールごと、カタログごとのカバレッジ
cargo fluent check                                                   # 両方のカタログにわたって .ftl 構文を検証する
cargo fluent fill --locale ja --model-provider anthropic.<alias>             # fill missing keys (default batch 50)
cargo fluent fill --locale ja --model-provider anthropic.<alias> --batch 10  # 小さいバッチ: リクエストごとのエントリ数を減らす (レート制限 / 切り詰めを緩和)
cargo fluent fill --locale ja --model-provider anthropic.<alias> --force     # すべてを再翻訳
cargo fluent scan                                                    # Rust ソースコードとの間で、期限切れまたは欠落したキーを検出する

1つのカタログに限定する: すべてのサブコマンドは --catalog <runtime|zerocode> を取ります（デフォルト: 両方）。TUIのみを翻訳するには:

cargo fluent fill --locale ja --model-provider anthropic.<alias> --catalog zerocode
cargo fluent check --catalog zerocode                                # syntax-check のみ zerocode

不明な --catalog 値は、有効な選択肢とともにエラーになります。

fill は、en/ ディレクトリを持つ選択されたすべてのカタログルートに対して <locale>/<domain>.ftl を生成します。ランタイムの cli.ftl/tools.ftl と zerocode の zerocode.ftl です。

プロバイダーの解決はランタイムと共有されます。 --model-provider は [providers.models.<kind>.<alias>] の下に設定された任意のエイリアスを受け付けます。すなわち、単独のエイリアス（<alias>）か、曖昧な場合は kind.alias 修飾子（anthropic.<alias>）です。このツールは実際のランタイムプロバイダーを構築するため、エンドポイント、認証ヘッダー、ワイヤプロトコルはファミリーごとに解決されます（Anthropic は /v1/messages + x-api-key、OpenAI 互換は /v1/chat/completions + Bearer など）。何も仮定されません。暗号化された api_key の値は、正規の SecretStore を通じて復号されます。設定と .secret-key をデフォルト以外の場所から読み込むには --config-dir <dir>（zeroclaw --config-dir に対応）を使用してください。デフォルトは ~/.zeroclaw、次に ~/.config/zeroclaw です。

バッチ処理: fill はバッチごとに1リクエストを送信します（N個のエントリすべてを単一のJSONオブジェクトとして）。--batch はNを小さくして、プロバイダのレート制限や長いエントリでのレスポンス切り詰めを緩和します。各バッチは次のリクエストの前にディスクへ書き込まれるため、実行途中での失敗では処理中のバッチのみが失われます。再実行すると、ターゲットの .ftl にすでに存在するキーはスキップされるため、再開は自動的です。--force は不要です。

zerocode 文字列（Fluent、独立）

apps/zerocode は、上記のランタイムカタログとは別に、独自の自己完結した Fluent セットアップを備えています。TUI は意図的にワークスペースの他の部分から切り離されており、zeroclaw-* クレートへの依存関係を持たず、その文字列は zeroclaw-runtime/locales/ 配下ではなくソースの隣に配置されています。

キー名前空間

すべての zerocode キーには zc- というプレフィックスが付き、ランタイムの cli-、channel-、tool- 名前空間と衝突することはありません。zc- 内の命名規則は zc-<pane>-<purpose> です。

• zc-pane-<name>: トップレベルのモードバーのラベル
• zc-app-<purpose>: app.rs が所有する文字列（ダイアログ、ヘルプ、ステータス）
• zc-<pane>-<purpose>: 特定のペインに固有の文字列 (zc-dashboard-*, zc-chat-*, …)

コードリテラルは翻訳されません

Ctrl+C、Esc、Shift+Up のようなコードグリフは、言語ではなくプロトコルです。HelpEntry と HelpNode のコンストラクターは、コードベクターを &'static str として、説明を String として受け取るため、コードリテラルはハードコードされたままで、説明は t() を通じて流れます。文章にコードをインラインで埋め込む場合は、{ $keys } という Fluent スロットを使用し、リテラルの周囲に翻訳済みテキストを連結するのではなく、レンダリング時にコードを渡してください。

ロケール解決

ロケールは zerocode の設定にあるトップレベルの locale フィールドから取得されます。未設定の場合、i18n::detect_locale() は --config-dir、次に ZEROCLAW_CONFIG_DIR、次に ~/.zeroclaw の順に解決された設定ディレクトリを読み込み、それでも見つからない場合は en にフォールバックします。zerocode は自身の設定からロケールを独立して解決し、デーモンのルックアップを共有しません。

文字列の追加

1. キー + 英語の値を apps/zerocode/locales/en/zerocode.ftl に追加します。カタログを見やすく保つため、セクションコメントを付けてソースファイルごとにキーをグループ化してください。
2. ソース内のリテラルを crate::i18n::t("zc-…") に置き換えます。enum→label の match アームでは、fluent_key() メソッドからキー定数（&'static str）を返し、レンダリング側で t() を呼び出します。文字列に対して match を行ってはいけません。
3. cargo check -p zerocode と i18n の単体テスト (cargo test -p zerocode i18n) は、コンパイル時/テスト時に欠落しているキーを検出します。実行時に欠落しているキーは {zc-key-name} として表示され、一度限りの stderr 警告を出力します。

翻訳の入力

cargo fluent はランタイムのカタログとともに zerocode カタログも走査するため、別個の fill コマンドは不要です。cargo fluent fill --locale <code> --model-provider <alias> を実行すると、ランタイムカタログを埋めるのと同じパスで apps/zerocode/locales/<code>/zerocode.ftl が生成されます。cargo fluent check と cargo fluent stats も同様に zerocode を報告します。scan は apps/ をインデックス化するため、zc- キー参照は zerocode のソースに対して解決されます。zerocode で翻訳を試すには、zeroclaw locales fetch 経由でインストールするか、上記の 2 つのディスク検索ルートのいずれかに配置してください。

ドキュメントの翻訳（gettext）

ドキュメントの翻訳は docs/book/po/ にあります。cargo mdbook sync は、抽出 → マージ → 廃止項目の削除 → AI 補完を 1 ステップで実行します。--model-provider を指定しない場合でも、sync は抽出とマージを実行し、翻訳が必要な文字列数を報告します。部分的な翻訳は、レンダリング時に英語にフォールバックされます。

cargo mdbook sync --model-provider anthropic.<alias>              # delta fill
cargo mdbook sync --model-provider anthropic.<alias> --force      # 品質パス：すべてのエントリを再翻訳
cargo mdbook sync --model-provider anthropic.<alias> --batch 1    # すべてのエントリの後に書き込む（最も安全な再開）
cargo mdbook sync --locale ja --model-provider anthropic.<alias>  # single locale
cargo mdbook sync --model-provider anthropic.<alias> --config-dir ~/.zeroclaw  # 修飾エイリアス + 明示的な設定ディレクトリ

--model-provider は cargo fluent と同じ共有ランタイムプロバイダパス（設定済みの任意のファミリー/エイリアス、ファミリーごとのエンドポイント + 認証 + ワイヤプロトコル、SecretStore の復号、--config-dir のサポート）を経由して解決されます。バッチ全体を1つの JSON オブジェクトとして送信する cargo fluent とは異なり、gettext フィラーは msgid → msgstr のマッピングを明確に保つためにソース文字列ごとに1リクエストを発行します。そのため --batch はリクエストのサイズではなく、.po がディスクにフラッシュされる頻度（チェックポイント間隔）を制御します。カタログ全体のロケールは数千の逐次リクエストになります。日常的な差分フィルには、安価なローカル Ollama エイリアスが経済的な選択肢です。

パイプラインには組み込みの耐障害性があります：

• 漏洩検出: モデルが翻訳の代わりに自身の指示を返した場合、ツールはそのパターンを（応答長の比率と箇条書きの構造から）検出し、応答の末尾から本来の翻訳を復元しようと試み、復元に失敗した場合はそのエントリを空白にして再翻訳します。
• 保護されたリテラルチェック: cargo mdbook check は、生成された .po ファイル内の高信頼度なリテラル破損も拒否します。ZeroClaw Maturity Framework などの製品名、zeroclaw daemon などのコマンドリテラル、フェンスで囲まれた TOML のセクション/キーリテラルは、翻訳内でもバイト単位でそのまま維持する必要があります。周囲の文章を翻訳し、機械向けのテキストは翻訳しないでください。
• パスリークチェック: 生成された翻訳は、英語ソースに存在しなかったマシンローカルの絶対パスを導入してはなりません。そのようなエントリは再翻訳のために空白にされ、cargo mdbook check によって拒否されます。
• 増分書き込み: 各バッチの後に .po ファイルが書き換えられます。実行中に Ctrl-C を押しても、その時点までの進捗は失われません。
• 廃止された文字列の削除: msgmerge と msgattrib --no-obsolete により、削除されたソース文字列が #~ エントリとして蓄積されるのを防ぎます。

メンテナは、Building the docs locallyに記載されている、英語ドキュメントの通常の例外を受け入れるべきです。.poの更新を求めるのは、PR自体が翻訳キャッシュのパス、リリース翻訳のパス、新しいロケールの変更である場合、または生成された差分がレビューできるほど小さい場合のみにしてください。

新しいロケールの追加

1. リポジトリのルートにある locales.toml を編集してください。これが唯一手を加える必要のあるファイルです:

2. アプリの文字列を翻訳してください。

   sh

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

3. ドキュメントの .po ファイルを初期化して埋める:

   sh

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

4. ステップ2の cargo fluent fill 実行は、cargo fluent がランタイムと zerocode の両方のカタログを走査するため、同じパスで apps/zerocode/locales/<code>/zerocode.ftl をすでに生成します。手動の zerocode ステップは不要です。カバレッジは cargo fluent stats で確認してください。

他のすべて、lang-switcher.js、CI のデプロイターゲット一覧、cargo mdbook locales の出力は、自動的に locales.toml から読み込まれます。

翻訳カタログのサブモジュール

翻訳済みの .po カタログは、このリポジトリのメインツリーには含まれていません。専用の zeroclaw-labs/zeroclaw-docs-translations リポジトリに置かれており、git サブモジュールとして docs/book/po（デフォルトブランチは main）にマウントされています。このマウントポイントはパス透過的です。book.toml の gettext プリプロセッサ、cargo mdbook sync、cargo mdbook build はいずれも、これまでと同じように po/ を読み込みます。

Rust クレートの開発ループでは、サブモジュールは一切必要ありません。サブモジュールが必要になるのは、docs のビルドと docs-deploy / release ジョブのみで、これらのチェックアウトでは submodules: recursive を指定します。それ以外はすべてサブモジュールなしのままです。

リリースごとに、scripts/release/refresh-translations.sh は変更されたカタログをサブモジュールの main ブランチにパブリッシュし、そのコミットに v{version} としてタグを付け、タグをチェックアウトして、メインリポジトリの gitlink をステージングします。bump-version.sh は翻訳のピン留めを意図的にそのヘルパーに委ねています。messages.pot と *.failures.log は再生成される成果物であり、両方のリポジトリで gitignore に登録されており、追跡されません。

リリース翻訳ワークフロー

リリース時のリフレッシュ、検証、タグ付け、プッシュ、gitlink ピン留め手順は、リリースランブックのステップ 2 に記載されています。このページは翻訳システムについて説明しています。リリースを準備する際の運用上の情報源としては、ランブックを参照してください。

モデル品質に関する注記

言語やモデルによって翻訳品質は大きく異なります。

リリース品質のパスには、--force オプションを使用してホストされたフロンティアモデルを優先してください。開発中の継続的なデルタフィリングには、ローカルの Ollama モデルが適しており、無料で利用できます。