ローカリゼーションカタログのライフサイクル

ZeroClaw には、形式と利用先が異なる 2 つのローカライズブランチがあります。Mozilla Fluent カタログは、ランタイムと zerocode のアプリケーション文字列を提供します。gettext カタログは、英語のソースと生成されたリファレンスをまとめた後、mdBook ドキュメントを翻訳します。

各ブランチはロケールレジストリと、プロバイダーを利用した補完方針を共有していますが、相互に置き換えられるものではありません。翻訳済みファイルがリポジトリで追跡されていることも、特定のバイナリがそれを埋め込んでいる、または読み込むことを証明するものではありません。このページを使用して、各カタログが英語ソースから生成、検証、ランタイムまたはサイトでの利用、リリースに至るまでを追跡してください。

2つのローカライズブランチ

locales.toml は、ロケールコードと表示ラベルの共有レジストリです。ドキュメントのロケールビルドと生成される言語スイッチャーを駆動し、ロケール検出のためにランタイムに埋め込まれます。それ自体ですべてのカタログがすべてのコンシューマーで利用可能になるわけではありません。各ローダーは、ファイルをどのように埋め込むか、またはディスク上で見つけるかを引き続き定義します。

Fluent アプリケーション文字列

英語のFluentファイルは、作成済みのソースファイルです。キーはメッセージを識別し、値には英語のテキストおよびFluentの変数が含まれています。製品名、コマンドリテラル、識別子、およびプレースホルダーは、メッセージの仕様上必要な箇所においてリテラルのまま保持されます。

cargo fluent はランタイムと zerocode のカタログルートを走査します。fill は各英語ファイルを選択したロケールと比較し、設定されたモデルプロバイダーを通じて不足しているキーを翻訳し、各バッチ後に進捗を書き込み、追跡対象の .ftl ファイルを変更します。check はカタログ構文を解析し、scan はソース参照とカタログを比較し、stats はカタログを変更せずにカバレッジを報告します。Fluent の差分は、付随的なアプリケーション作業ではなく、意図的なローカリゼーション変更に含めるべきです。

保存と読み込みは別々の関心事です:

• ランタイムのCLI文字列には常に英語が埋め込まれています。ローダーはbuiltin_cli_ftl_sourceによって埋め込まれた翻訳済みCLIカタログを使用することもでき、その後、最高優先度のロケールソースとしてディスクカタログを適用します。
• ランタイムのプロンプト向けツール説明には常に埋め込み英語が含まれ、ディスク上の翻訳済み tools.ftl の値がオーバーレイされます。任意項目の欠落したルックアップは値を返しません。
• zeroclaw-tools は、そのクレートが runtime に依存できないため、英語を独立して埋め込み、ツール所有のスキーマおよび結果文字列用にディスク上の tools.ftl を読み込みます。必須のルックアップが見つからない場合は、可視の {key} マーカーをレンダリングします。
• zerocode は英語のカタログを埋め込み、ディスクから翻訳済みの zerocode.ftl を重ねて適用します。ZEROCODE_LOCALE_DIR は明示的なテスト用のオーバーライドで、通常の共有場所は <config-dir>/data/ftl/<locale>/zerocode.ftl です。
• zeroclaw locales fetch は、zeroclaw-config で宣言されたカタログパスを使用して、選択したランタイムおよび zerocode カタログを、その共有ディスクロケールディレクトリにダウンロードします。

ランタイム、ツール、およびzerocode については、英語がベースマップとなります。翻訳済みディスクまたは組み込みカタログは、含まれるキーを置き換えます。翻訳されていないキーは英語の値を保持します。必須のルックアップは、利用可能なすべてのソースに存在しないキーを報告し、テキストをサイレントに生成するのではなく、表示可能な {key} マーカーをレンダリングします。オプションのランタイムツール説明ルックアップは値を返しません。

gettext ドキュメント文字列

英語の Markdown は作成元となるドキュメントソースですが、抽出では、生成されたリファレンス、インクルードされたスニペット、抽出用ビルド向けに実体化されたプリプロセッサーの出力も対象になります。xgettext の出力を使って mdBook を実行する前に、cargo mdbook sync は、ロケールビルドと単一ロケールでのサービングで使用される共有の prepare_generated_book_inputs() パスを呼び出します。このパスは、CLI と設定のリファレンス、ロケールスイッチャー、テーマ、キーマップ、ハードウェア、feature-matrix、プラグインの入力を、それぞれの正規のソースから再生成します。抽出もビルド済みの peer-groups プリプロセッサーを使って実行されるため、クリーンチェックアウトは、無視対象ファイルや以前のドキュメントビルドで残されたバイナリに依存しません。

cargo mdbook sync は英語のメッセージを messages.pot に抽出し、テンプレートを正規化し、ファジーマッチングなしで各ロケールをブートストラップまたはマージし、廃止されたエントリを削除して、未翻訳のデルタをレポートします。モデルプロバイダーが指定された場合は tools/fill-translations を通じて不足している翻訳を補完し、指定されない場合はプロバイダーへの呼び出しを行いません。コマンドオプションと操作手順はメンテナーガイドが管理します。

fill ツールは、1 つの gettext エントリを 1 つのソースから翻訳へのマッピングとして扱います。プロンプト漏えいや新しいマシンローカルの絶対パスを含むモデル応答を修復またはクリアし、必要な末尾の改行を保持し、インクリメンタルに書き込み、受理されたエントリから fuzzy フラグを削除します。cargo mdbook check は、すべての PO ファイルを個別に解析し、不審な生成レスポンス、破損した保護対象リテラル、混入したローカルパスを拒否します。

部分翻訳とフォールバック

gettext プリプロセッサは、ロケールにそのエントリの使用可能な翻訳値がない場合、英語の msgid を表示します。そのため、ロケールでは、翻訳済みのナビゲーションや段落と、新しく追加された英語の文章が併せて表示されることがあります。この混在した言語状態は、英語の原文がカタログで対応済みの範囲を超えて更新されたことを意味します。mdBook が1ページに対して2つの言語を選択したという意味ではありません。

一般的な原因は次のとおりです:

• 英語のドキュメントまたは生成されたリファレンスの変更により、新しい msgid が追加されました。
• カタログの同期で新しいソースがマージされましたが、翻訳の補完処理がまだ実行されていません。
• 安全修正により、漏洩した、パスを含む、またはその他の理由で使用できないモデル応答がマスクされた;
• ソース編集により古いメッセージが新しいメッセージに置き換えられました。
• ロケールカタログまたはリリースピンが意図的に現在の master より遅れています。

Fuzzy はカタログ保守の状態であり、古い値をそのまま表示しても安全であることを保証するものではありません。現在の sync コマンドは新しいマージに対して fuzzy マッチングを無効にしますが、fill ツールは既存の空でない fuzzy 値を受け入れて、そのフラグを削除できます。結果として得られる msgstr を確認してください。フラグだけから公開時の挙動を推測しないでください。

翻訳されたロケールのビルドでは、全文検索が無効になります。検索インデックスが作成されるのは、locales.toml の最初のエントリであるプライマリロケールのみです。これは、翻訳カバレッジの欠如ではなく、build_locales におけるサイズ上の判断によるものです。

カタログのストレージとリリースピン

Fluent カタログはメインリポジトリにあります。通常の Fluent 翻訳変更では、対象の .ftl ファイルを直接更新し、それらのキーを使用するアプリケーションコードとともにレビューされるか、翻訳に特化した作業としてレビューされます。

ドキュメントの PO カタログは zeroclaw-labs/zeroclaw-docs-translations にあり、Git サブモジュールとして docs/book/po にマウントされています。メインリポジトリには各 PO ファイルではなく、1 つの gitlink コミットが記録されます。messages.pot と翻訳失敗ログは生成された成果物であり、固定されたカタログセットには含まれません。

リリースヘルパー scripts/release/refresh-translations.sh は、翻訳タグとメインリポジトリの gitlink 更新を担当します。デフォルトでは sync とカタログチェックを実行し、サブモジュール内のカタログ変更をコミットしてプッシュし、対応する v<version> タグを作成してチェックアウトし、gitlink をステージします。その --no-translate モードは sync とカタログチェックの両方をスキップするため、現在のカタログが別途検証済みの場合にのみ適しています。translation-pin ワークフローは、正確に固定されたコミットを初期化し、PO 構文をチェックし、ロケールカタログが同じ msgid セットを公開していることを検証します。

ドキュメントのデプロイでは、固定されたサブモジュールを初期化し、すでに存在するすべてのロケールをビルドします。モデルプロバイダーを呼び出したり、不足している翻訳を補完したり、サブモジュールを更新したり、リリースタグを作成したりすることはありません。

検証とレビューの境界

• 通常の英語ドキュメント PR では、広範な PO の変更ノイズを、translation-cache に集中したパスに先送りしてもかまいません。元の PR では、英語ソースと生成物の境界をレビューしてください。

• 翻訳やカタログ保守が目的である場合、ロケールを追加している場合、生成される差分が小さくレビュー可能である場合、またはリリースパスがピンを進めている場合は、PO の変更を含めます。

• キーまたは翻訳されたアプリケーション文字列が変更される場合は、Fluent の変更も含めてください。その .ftl ファイルが存在するというだけで、翻訳されたランタイムパスが機能すると主張しないでください。関連するローダーまたはフェッチ/インストールパスを検証してください。

• 承知しました。機械向けの例（コマンド構文、設定キー、製品名、JSON/TOMLリテラル、プレースホルダーなど）はそのまま保持し、周囲の説明文のみを日本語に翻訳します。

  何か翻訳が必要な文字列がありましたら、お知らせください。

• 英語のフォールバックは、承認済みカタログのカバレッジが不足していることを示す明白な証拠として扱ってください。レンダリングされた HTML ではなく、カタログのソースを修正または補完してください。

• サブモジュールの変更をリリース/カタログ操作としてレビューする: メインリポジトリの gitlink と、それが選択するカタログコミットの両方を検査します。

詳細なコマンド、プロバイダー設定、バッチ処理、ロケールの追加、リリース手順については、Docs & Translations を参照してください。gettext 抽出に供給される英語ソースおよび生成リファレンスの各ステージについては、Generated documentation pipeline を参照してください。

ソースポインタ

• ロケールレジストリ: locales.toml
• ランタイム Fluent ローダー: crates/zeroclaw-runtime/src/i18n.rs
• ツール側で管理する Fluent ローダー: crates/zeroclaw-tools/src/i18n.rs
• ランタイム Fluent カタログ: crates/zeroclaw-runtime/locales/
• zerocode Fluentローダー: apps/zerocode/src/i18n.rs
• zerocode Fluentカタログ: apps/zerocode/locales/
• Fluent ツール: xtask/src/cmd/fluent/
• カタログダウンロードマップ: zeroclaw_config::schema::FTL_CATALOGS
• gettextの抽出とマージ: xtask/src/cmd/mdbook/sync.rs
• gettext 安全チェック: xtask/src/cmd/mdbook/check.rs
• gettext の補完と修復: tools/fill-translations/
• ロケールのビルドおよび検索動作: xtask/src/cmd/mdbook/build.rs
• 翻訳ピンの検証: .github/workflows/validate-translations-pin.yml
• リリースカタログの更新: scripts/release/refresh-translations.sh
• ドキュメントのデプロイ: .github/workflows/docs-deploy.yml