ドキュメント翻訳ワークフロー

March 18, 2026 · View on GitHub

docs/i18n ディレクトリでは翻訳設定とツールを一元管理します。英語ファイルが常に唯一のソースであり、翻訳は <name>.<language-code>.<ext> 形式（例: README.ja.md）で元ファイルと同じ場所に配置します。

設定

manifest.json に翻訳対象のファイルとメンテナンス対象の言語を記述します。主なキーは次の通りです。

  • primary_language – 正準言語（英語）。
  • target_languages – 追加言語。ISO 言語コード、表示名、必要に応じた現地語表記 (autonym)、文字方向を含みます。
  • include – リポジトリルートからの相対パスで指定するグロブパターン。翻訳対象に含めたいファイルを指定します。
  • exclude – ミラー対象外とするファイルやディレクトリを除外するグロブパターン。

新しいドキュメントディレクトリや言語を追加するときは、このマニフェストを更新してください。

現在の対象言語:

  • 日本語 (ja, 日本語, LTR)
  • ヘブライ語 (he, עברית, RTL)
  • スペイン語 (es, Español, LTR)
  • ポルトガル語 (pt, Português, LTR)
  • フランス語 (fr, Français, LTR)
  • ロシア語 (ru, Русский, LTR)
  • アラビア語 (ar, العربية, RTL)
  • ウルドゥー語 (ur, اردو, RTL)

翻訳スタブの生成

リポジトリルートで以下を実行するとプレースホルダーを生成できます。

python3 scripts/sync_docs_i18n.py

スクリプトは include で一致した英語のソースドキュメントを走査し、すでに翻訳ファイルが存在するパスを除外したうえで、翻訳者向けのメタデータを含むスタブを作成します。変更内容を事前確認したい場合は --dry-run を、特定言語だけ生成したい場合は --lang <code> を指定してください。

翻訳作業

  • スタブの本文を翻訳した内容に置き換え、フロントマター内の status を（in-progress や complete など）適切な値に更新します。
  • フロントマターのキーはツールが進捗を追跡できるよう維持してください。
  • 元の英文ドキュメントを移動または改名した場合は、対応する翻訳ファイルのファイル名も合わせて更新します。

新しい言語の追加

  1. manifest.json の target_languages に新しいエントリを追加します。
  2. python3 scripts/sync_docs_i18n.py --lang <code> を実行してスタブを生成します。
  3. 作成されたファイルを翻訳します。
  4. サイトジェネレーターなど公開パイプラインがあれば、新しい言語を表示対象として組み込みます。

CI への統合

将来的には、各ソースドキュメントに対してすべての言語スタブが存在するかを CI で検証できます。簡易的にはスクリプトを --dry-run で実行し、スタブ作成予定がある場合にジョブを失敗させる方法が考えられます。現状のリポジトリでは未導入ですが、スクリプトの出力は機械処理しやすい形式になっています。