> Source: https://clickhouse.github.io/loom/ja/architecture/documentation-translation/ (Markdown: https://clickhouse.github.io/loom/ja/architecture/documentation-translation.md)

> この機械翻訳の作成後に英語の原文が更新されています。最新の手順は[英語のページ](https://clickhouse.github.io/loom/architecture/documentation-translation/)を参照してください。

<!-- i18n: source=docs/architecture/documentation-translation.md blob=f3c39bd59c115e29a52e9ce3c79a91bd7e85666a model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/architecture/documentation-translation/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/documentation-translation/), which is authoritative.

<a id="documentation-translation-requests"></a>

# ドキュメント翻訳リクエスト

翻訳ジェネレーターは、準備済みの英語テキストを上限付きのリクエストに分割し、組み立てた翻訳を書き込む前に検査します。英語が常に正本です。

<a id="request-planning"></a>

## リクエストの計画

`english_requests` は、ページ全体で共通の 1 つのカウンターを使って見出しアンカーを割り当てます。安全な 2 階層目の見出しでの分割を優先し、サイズの大きいセクションは最大 16 KiB のソーススライスにまとめます。スライスを改行で連結すると、アンカー付きの英語が正確に復元されます。

プランナーは、リスト項目、コードブロック、テーブル行について CommonMark のトークンのソース範囲を使用します。フェンス付きコードとインデントコード、インラインコード、完全な HTML 要素、コメントは分割されずにまとまります。テーブルのヘッダーは区切り行と一緒に保たれます。分割できない大きな単位がある場合は、そのページの最初のモデル呼び出しの前に拒否されます。コストの見積もりは、翻訳と同じリクエスト一覧を使用します。

サイトのリスト拡張は、順序付き項目を含め、2 スペースの継続行を受け付けます。そのパーサーにはソースマップがないため、インデントのスキャンによって、CommonMark の範囲と合わせてこれらの項目を保護します。どちらの方言の項目も分割されません。

サイト拡張のテーブルの中には、CommonMark ではインデントコードになるものがあります。そのコード範囲は分割されないため、この曖昧さを持つ大きなブロックは、プロバイダーへの受け入れの前に拒否されます。テーブルを拡張コンテナの外に移動すれば、英語側でこの曖昧さを解消できます。

<a id="original-unit-reconciliation"></a>

## 元の単位の照合

`reconcile_completed_units` は、英語の編集をまたいで完了済みのリクエストを保持するための純粋な計画 API です。過去と現在の `PreparedSource` コンテナ、およびダイジェスト付きの完全な `OriginalUnit` マニフェストを受け取ります。どちらのコンテナにも、準備済みのリンクとページ全体のアンカーが含まれます。元の範囲とソースハッシュはすべて過去のコンテナと一致する必要があり、範囲間の隙間は空文字列または LF のみでなければなりません。マニフェストのダイジェストは、選択された各応答の参照を含むこのメタデータを束縛します。

呼び出し側は、元の計画全体と完了状態を、リクエスト台帳、キャッシュ、選択された応答の受領記録と照らして認証します。キャッシュファイルがないことは何の証明にもなりません。`reply_ref=None` の元の単位は、不確かな試行が解決された後に完了済みの応答がないことを明示的に証明します。確認済みの障害を持つ完了済みの応答は、その参照と `UnitFault` を保持します。参照を省略して未完了の作業にすることはできません。呼び出し側は、ソースのバージョンをまたいだロケールとソースの組み合わせ全体に対する拒否情報も提供します。

計画が保持するのは、現在のパーサー上安全な境界にある、一意で単調な、バイト単位で同一の完了済みの単位全体のみです。ペイロードは末尾の改行を自身で持つことも、1 つの LF を組み立てに任せることもでき、連続するペイロードは連続したままです。各処置は、現在の `SourceContext`、元の出自、障害の識別子、正確な区切りを保持します。完了済みの単位は、プロバイダー呼び出しなしで再利用する場合、リクエストの上限を超えることがあります。未完了の隙間と挿入された英語は、保持された範囲の外で、上限付きのプランナーを使用します。`chunks.split` は `source_context` を受け取るため、ヘッダーのないテーブルのスライスは、現在のテーブル全体の行境界を使用します。

処置は、再利用、同一入力の修正、入力の変更、未完了の作業を区別します。1 つの元の単位に影響するソースの編集と障害は、1 つの入力変更の処置にまとめられます。候補の重複、範囲の重なりや順序の入れ替わり、安全でない境界、不明な障害、組み合わせの拒否は、競合として返されます。一致しない複数の元の単位の中に変更された完了済みの単位がある場合は、対応する分割位置が証明されている必要があり、プランナーは分割を推測しません。ページ全体にわたる完了済みの単位の置き換えはサポートされていません。ページ全体の完全一致による再利用は引き続き可能ですが、この API はあらゆる変更後のページの対応付けを解決するわけではありません。

`chunks.split` と `reconcile_completed_units` はどちらも、真偽値を除く 1 から 16384 までの整数 `bounded_new_request_bytes` を受け付けます。デフォルトでは 16 KiB の分割が維持されます。この上限は、入力変更や同一入力の修正を含む、今後発行されるすべてのリクエストに適用されます。再利用される完了済みの単位は、この上限を超えても全体のまま保持されます。上限に収まらない、変更または障害のある完了済みの単位は、分割されずに競合として返されます。

下限を小さくすると、切り詰められた応答の後の未完了の作業を細分化できる場合があります。呼び出し側は、確定したリクエスト、ソース範囲、応答、使用量、すべての完了状態と拒否状態、およびその後の台帳エントリを認証します。その実行パケットは、選択された上限と、対応する範囲や保持された完了済みの参照を含む現在の計画そのものを束縛します。上限だけではこの証拠は成立せず、保留の解除もプロバイダー呼び出しの受け入れもできません。切り詰められた応答の先頭部分は完了済みの単位ではなく、入力を小さくしても応答が完全になる保証はありません。

`translate_text` は、入力変更の制約のために、現在のソースコンテキスト付きで信頼できる `initial_feedback` を受け付けます。`request_system` は、その正確なフィードバックを、プロバイダーに送信する正規の SYSTEM に含めるため、実際のリクエストペイロードが制約を束縛します。フィードバックは、表示可能な ASCII 文字と LF の 4096 バイトまでに制限され、空のフィードバックではデフォルトの SYSTEM が維持されます。最初のメッセージには現在の英語のみが含まれます。古い入力に対するアシスタントの応答は再送されず、機械的な再試行で使えるのは現在の入力に対して返された応答のみです。無効なフィードバックやソースコンテキストの不一致は、課金やプロバイダー呼び出しの前に拒否されます。

照合の計画は、応答の解決、プロバイダー呼び出しの受け入れ、出力の書き込みを行いません。利用側は、解決された応答を認証して現在のコンテキストに対して検証し、続いて組み立てたページ全体を検証します。内容の不変条件と両方のテーブル方言の検査は引き続き適用されます。公開には、現在の英語に対する意味面と言語面の網羅性のレビューも必要です。構造上の成功は、確認済みの障害や拒否を解消しません。

<a id="assembled-validation"></a>

## 組み立て後の検証

組み立てたページは、出力ディレクトリやファイルが作成される前に、既存の内容の不変条件とテーブル検査を通過します。テーブル検査では、ドキュメントサイトの Markdown パーサーと、テーブル拡張付きの CommonMark の両方を使用します。両者はコンテナの規則が異なります。検査では、テーブルのグループ、行、セル、配置、セルが空かどうかを保持します。サイトのリスト、注意書き、コードの拡張も検査の対象です。セルのテキストは、シリアライズと生の HTML の復元の後に測定されるため、空のマークアップで欠落したテキストを隠すことはできず、エスケープされたリテラルのタグはテキストのままです。

パーサーのパッケージは、翻訳の requirements と開発用 extra でバージョンが固定されています。サイトのパーサーのバージョン固定は、ドキュメントビルダーと一致します。ソースのバイト数の上限は、翻訳された応答が出力トークンの上限に収まることを保証しません。切り詰められた応答は引き続き失敗として扱われ、構造検査は翻訳の品質や本文の完全性を保証しません。

<a id="source-spelling-contracts"></a>

## ソースの綴りに関する契約

ラベルの検証では、ソースの綴りと通常の説明を区別します。ソース固有の名前の宣言は、正確な製品名とプロジェクト名の範囲を保護します。ファイル名のラベルは、そのソースのリンク先にある追跡対象のリポジトリファイルと一致する必要があり、慣例的な `README` というラベルは `.md` の接尾辞を省略できます。操作フィールドの宣言は、返される文字列の語彙と、文書化された 1 つのフィールドの式を保護します。説明全体が引用符付きの識別子の選択肢である文字列型のフィールドも、リテラル値を宣言します。引用符、大文字小文字、ファイル名に似た綴りだけでは、例外は認められません。

これらの宣言にはソースの根拠が必要です。パッケージやプロジェクトの識別情報、明示的な用語、実在するファイルのリンク先、または操作のワイヤー契約です。これらのソースの宣言を変更する場合は、その証明と、対応する回帰テストのケースを確認する必要があります。保護された範囲の前後にある通常の修飾語句は、引き続きラベルの検証の対象です。

テーブルのセル（エスケープされたパイプやインラインコード内のパイプを含む）は、既存のサイトパーサーと CommonMark パーサーから取得されます。上限付きの各リクエストは、プロバイダーに周囲のテキストを送信することなく、完全な英語のコンテナ内で検査されます。ソースマップのないサイト専用のセルは、ページの組み立て時に検査されます。再試行、組み立て、保存済みページの検査は同じ規則を共有しており、保護された範囲は、その綴り、出現順、ソースのラベルまたはフィールドを保持しなければなりません。これは有限のソース契約であり、言語の分類器でも意味面のレビューでもありません。

<a id="invariants"></a>

## 不変条件

- プロバイダーに送信されるソースのスライスはすべて上限内に収まり、すべてのソースのバイトとページ全体のアンカーは組み立て後も保持されます。再利用される完了済みの単位は、ペイロード全体を保持します。
- 分割できない単位は、プロバイダーへの受け入れの前に拒否されます。
- プロバイダーの設定、出力トークンの上限、再試行、累積の財務チェックは、ページの分割方法とは無関係に、すべてのリクエストを個別に制御します。
- 出力は、組み立て後の検証が成功した後にのみ書き込まれます。

<a id="source-entry-points"></a>

## ソースのエントリポイント

- `scripts/i18n/translate.py`：`english_requests`、`request_chars`、`translate_page`。
- `scripts/i18n/translate.py`：`request_system`、`translate_text` と初期フィードバック。
- `scripts/i18n/reconcile.py`：`reconcile_completed_units`、`OriginalUnit` とマニフェストの束縛。
- `scripts/i18n/chunks.py`：保護された範囲、コンテキストに応じたソースの分割、パース済みのテーブルセル。
- `scripts/i18n/context.py`：ソースの綴りの宣言と、残りのラベルの射影。
- `scripts/i18n/requirements.in`：翻訳のランタイム依存関係。
