二言語ドキュメントの整合性を保つ
公開ユーザーガイドは、相対パスでペアになります：
docs/ja/<相対パス>
docs/en/<相対パス>
英語は / に公開され、日本語は /ja/ に公開されます。日本語は新しい製品説明の実用的な作成元であり続けますが、どちらかの言語での編集が、もう一方の言語に異なる動作、コマンド、所有権の境界、警告、ナビゲーションを黙って残してはなりません。
範囲
このワークフローを、両方の言語ルートの index.md と guide/**/*.md に適用します。docs/en/reference/ は意図的に英語のみとします。内部アーキテクチャ、意思決定、リポジトリ、コントリビューター、およびフォワードテスト文書は、二言語ルートの外側にあるため、翻訳ペアではありません。
ワークフロー
- 要求された変更と現在のGit差分を検査します。影響を受けるすべての公開ページと、同じ相対パスを持つその対応ページを特定します。
- 両方の完全なページを読みます。日本語コンテンツが作成、編集、または可読性のためにレビューされる場合は、日本語スタイルリファレンスも読んでください。編集が製品の動作、コマンド、パス、所有権を変更する場合は、翻訳の前提ではなく、現在のソースまたは承認された意思決定を検証します。
- 意味、情報アーキテクチャ、例、警告、リンク先は保持しますが、各読者向けに自然なドキュメントを書き、文単位で翻訳しないでください。意味や情報構造が変更された場合は、両方の対応ページを編集します。日本語のみの表現改善の場合は、英語の対応ページを検査しますが、その意味と構造がすでに一致している場合は、英語の編集をでっち上げないでください。
- 対応ページが存在しない場合は、作成します。ページが意図的に言語固有である場合は、それがペア範囲外であることを確認するか、延期するという明示的な決定を得て、延期とその追跡場所を報告します。乖離が単に言及されていない状態で、二言語変更を完了と呼んではいけません。
- 移動または削除の場合は、両方のツリーに同じ相対パスの変更を適用し、
mkdocs.yml、インバウンドリンク、コントリビューターガイダンス、およびコードやテストに埋め込まれた公開URLを更新します。
検証
リポジトリルートから実行します：
python -m mkdocs build --strict
git diff --check
生成された英語と日本語のページが対応するパスに存在すること、およびそれらの言語セレクターリンクが相互にリンクしていることを確認します。公開URLがCLI契約である場合は、そのソース、フォーカステスト、および承認された意思決定も更新し、フォーカステストと python scripts/check_decisions.py を実行します。
検査および変更されたページペア、意味比較後に意図的に変更されていない対応ページ、その他の例外、および検証結果を報告します。