国際化と機械翻訳¶

ドキュメントは英語と簡体字中国語をレビュー済みの規範ソースと見なします。他のすべての有効な言語は自動生成された派生物です。言語レジストリ、ソースルーティング、モデル構成、API制限はi18n/config.tomlにあります。

1. 言語カバレッジとソースルーティング¶

レジストリは意図的にカバレッジを12のサイト言語に収束させています。これには国連の6つの公用語（アラビア語、中国語、英語、フランス語、ロシア語、スペイン語）が含まれ、東アジアからは日本語、韓国語、繁体字中国語が、ヨーロッパからはドイツ語、イタリア語、ポルトガル語が追加されています。英語と簡体字中国語は規範ソースであるため、機械翻訳される言語は合計10言語です。

日本語、韓国語、繁体字中国語は簡体字中国語をソースとし、他のすべての派生言語は英語をソースとします。各言語のソースは構成で明示的に指定されており、翻訳者は言語名やドキュメントの文字に基づいて推測しません。

新しい言語を追加する場合は、i18n/config.tomlとMkDocs i18n言語リストの両方を更新する必要があります。ドキュメント監査は、2つのレジストリが一致しない状態を拒否します。

2. 規範ドキュメント契約¶

各MkDocsページには、英語ファイルと.zh-CN.mdファイルの両方が必要です。Pull request、mainへのプッシュ、または手動でトリガーされた品質チェックで規範バージョンのいずれかが変更された場合、チェック対象のコミット範囲内に他のバージョンを含める必要があります。品質ワークフローは以下をチェックします：

規範ドキュメントのペアリングと変更のペアリング；
見出しレベルとコードフェンスの一貫性；
ローカルリンクとソース参照；
フィクスチャとテストマニフェスト；
すべての構成済み言語での厳格なビルド。

規範コンテンツは人間が作成することも、AIを利用することもできますが、通常のソースコードとしてコミットおよびレビューされる必要があります。Pull requestワークフローは翻訳APIを決して呼び出しません。

3. 見出し番号とフラグメントリンクの安定性¶

Markdownソースドキュメントは、説明的な見出しテキストのみを保存し、アウトライン番号は保存しません。MkDocsビルドのたびに、scripts/mkdocs_heading_numbers.pyがH2～H6にページ内番号を追加します。使用ガイドページのH2は小文字（a.、b.）を使用し、より深いレベルは文字と10進数（a.1、a.1.1）を使用します。他のページは引き続き10進数のページアウトラインを使用します。左側の使用ガイドナビゲーションは、1.1のような単一レベルの10進数番号を個別に使用します。H1ページタイトルとトップレベルのナビゲーションカテゴリには番号が付けられません。生成された番号は表示メタデータです：セクションを移動すると表示番号は変わりますが、フラグメント識別子は変わりません。

ビルドフックは、表示番号を追加する前に、各見出しの明示的な識別子を固定します。i18n/legacy-heading-anchors.jsonは、手動で書かれた番号が削除される前に公開されたフラグメントエイリアスを保持します。この生成された互換性マッピングを編集したり、規範または派生Markdownに手動のアウトライン番号を再追加したりしないでください。ドキュメント監査はそのようなコンテンツを拒否します。

4. 派生ドキュメント契約¶

生成されたページは、index.fr.mdやguide/configuration.ja.mdのようなMkDocsサフィックスパターンを使用します。各ページには、以下を記録する決定論的なフロントマターが含まれています：

規範ソースの言語とパス；
ソースファイルのSHA-256ダイジェスト；
実際に使用されたモデルとプロンプトのバージョン；
このページが機械翻訳であること。

i18n/manifest.jsonは、出力ダイジェストと翻訳入力フィンガープリントも記録します。ソース、用語集、プロンプト、モデル、または生成出力が変更された場合、ページは期限切れと見なされます。完全な再構築が明示的に要求されない限り、翻訳者は期限切れのユニットのみを要求します。

翻訳された見出しはローカライズされた自然なスラッグを保持し、規範ソーススラッグの隠しエイリアスも取得します。Markdownリンクターゲットはそれ以外の場合保護され、モデルによる変更が許可されないため、これらのエイリアスは同一ページおよびページ間のフラグメントリンクがすべての言語で機能することを保証します。エイリアスはオフラインでリフレッシュでき、翻訳APIを再度呼び出す必要はありません。

生成ファイルは手動で編集してはいけません。メインブランチの翻訳ワークフローはこれらのファイルを再生成し、各言語の完了後にその言語を1つのバッチとして、品質チェックの正確なSHAから派生したgenerated-onlyブランチにコミットします。後続の実行はそのブランチを検証してから再利用するため、中断が発生しても処理中の1つの言語のみが失われます。ワークフローは、派生言語監査、完全なテストスイート、およびすべての言語での厳格なビルドが完了するまで、mainを変更しません。すべての検証が合格した後、ワークフローはmainが進んでいないことを再度確認し、fast-forwardプッシュでチェックポイントを進め、同じ検証済みのサイトアーティファクトをデプロイします。

5. Markdown保護とプロンプト契約¶

APIリクエストを送信する前に、翻訳者はフロントマター、フェンスコード、インラインコード、リンクターゲット、HTMLタグ、ベアURLを不変のプレースホルダに置き換えます。プレースホルダが欠落、重複、出現、または契約に従って復元できない場合、レスポンスは拒否されます。

プロンプトはまた、見出しレベルとコードフェンス言語の一貫性を要求します。実装は、保護されたコンテンツを復元した後、これらの属性を独立して検証します。翻訳出力はJSONオブジェクトでなければなりません。JSON以外の説明テキスト、空のコンテンツ、異常終了の理由、または互換性のないデータ構造はすべて失敗と見なされます。

Markdownとナビゲーション目次のプロンプトはi18n/prompts/で個別にバージョン管理されています。i18n/glossary.jsonは安定した製品名とコマンド用語を保持します。

6. モデル構成と認証情報¶

デフォルトのモデル構成はdeepseek-v4-flashです。実装はこの名前に対して条件分岐を書きません。将来モデルを変更する場合は、i18n/config.tomlを変更するか、--modelを渡すか、DEEPSEEK_TRANSLATION_MODELワークフロー変数を設定するだけです。最終的に解決されたモデルは、各生成ページとマニフェストエントリに記録されます。

GitHub Actionsは、DEEKSEEK_API_KEYという名前のリポジトリシークレットからのみAPI認証情報を読み取ります。オフラインプランが保留中のAPI翻訳ユニットを示している場合にのみ、生成ステップはそのシークレットを取得します。信頼できないpull requestコード、およびAPIを必要としない計画、クリーンアップ、検証ステップはシークレットにアクセスできません。認証値はログ、生成ファイル、アーティファクト、またはマニフェストに決して書き込まれません。

7. ページ通知と言語設定¶

機械生成ページはレンダリング時にローカライズされた警告を取得します。この警告は、ページがAIによって翻訳されたことを説明し、信頼できる英語または簡体字中国語の原文へのリンクと、事前入力された翻訳問題レポートへのリンクを提供します。通知は翻訳されたMarkdownの一部ではなく、目次エントリも生成しません。

訪問者が初めてサイトのルートページを開くと、サイトはnavigator.languagesを構成済みの言語オプションと比較し、互換性がある場合は対応する言語を選択します。ユーザーが手動で選択した言語はローカルに保存され、今後の訪問で優先されます。

8. メンテナンスコマンド¶

ネットワークリクエストを行わずに翻訳待ちユニットの数を表示する：

uv run python scripts/translate_docs.py --plan

すべての生成ページと目次翻訳が最新であることを検証する：

uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required

APIを呼び出さずに安定したソース見出しエイリアスをリフレッシュする：

uv run python scripts/translate_docs.py --refresh-heading-anchors

明示的なモデルを使用して完全な再構築を強制する：

DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
  --force --model deepseek-v4-flash

自動ワークフローはリポジトリシークレットを使用し、キーをコマンドラインに配置しません。