コンテンツにスキップ

国際化

CodexSpec は LLM による動的翻訳 で複数言語をサポートし、GitHub Pages 向けには 多言語ドキュメント を提供します。

コマンドテンプレートの翻訳

仕組み

  1. 単一の英語テンプレート: すべてのコマンドテンプレートは英語のまま保持
  2. 言語設定: プロジェクトが希望する出力言語を指定
  3. 動的翻訳: Claude が実行時にコンテンツを翻訳

言語の次元

CodexSpec は言語を、個別に設定可能な 4 つの次元に分割します。output がベースであり、それ以外は output を上書きしつつ、未設定時は output (さらに en) にフォールバックします。

次元 config.yml のキー init で設定 後から設定 制御する対象 フォールバック先
出力 (ベース) output --lang config --set-lang 他の 3 つのベース en
対話 interaction --interaction-lang config --set-interaction-lang LLM の対話 + CLI 出力 output → en
ドキュメント document --document-lang config --set-document-lang 生成される requirements/spec/plan/tasks output → en
コミット commit --commit-lang config --set-commit-lang git コミットメッセージ output → en
テンプレート templates — — コマンドテンプレートのソース (常に en) —

言語の設定

初期化時に設定

# 中国語で出力 (出力のベースを設定)
codexspec init my-project --lang zh-CN

# 完全非対話: 出力ベースを zh-CN、コミットメッセージを英語
codexspec init my-project --lang zh-CN --commit-lang en

# すべての次元を明示的に指定 (スクリプト可能、プロンプトなし)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

TTY 環境で --lang を付けずに (かつ 3 つの次元フラグもすべて付けずに) 初めて init を実行すると、ベース言語のプロンプトが出ます。非 TTY (CI/スクリプト) では en がデフォルトです。init を再実行しても、指定しなかった言語キーは保持されます。

初期化後に設定

# 現在の設定を表示
codexspec config

# 単一次次元を変更
codexspec config --set-lang zh-CN
codexspec config --set-interaction-lang zh-CN
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# workflow.auto_next の切り替え (フラグ単独でトグル、on/off を明示的に渡すことも可能)
codexspec config --auto-next

# サポートされている言語の一覧
codexspec config --list-langs

設定ファイル

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # ベース言語。以下の 3 つはここにフォールバックし、さらに "en" にフォールバック
  interaction: "zh-CN"   # LLM の対話 + codexspec CLI の出力 (任意 → デフォルトは output)
  document: "en"         # 生成される requirements/spec/plan/tasks (任意 → デフォルトは output)
  commit: "en"           # git コミットメッセージ (任意 → デフォルトは output)
  templates: "en"        # "en" のまま保持

project:
  ai: "claude"          # claude | codex | both ― このプロジェクトが対象とする AI アシスタント
  created: "2025-02-15"

GitHub Pages ドキュメントの i18n

ドキュメントサイトの言語と CLI/ランタイムの言語は混同しないでください。

  • ドキュメントサイト (この節): 8 言語。 MkDocs がビルドする GitHub Pages サイトは、下記の 8 ロケール (en, zh, ja, ko, es, fr, de, pt-BR) だけを公開します。これは docs/{lang}/ のディレクトリ構造と mkdocs-i18n プラグインによって決まる 固定 のセットです。
  • CLI / ランタイム (上の節): 13 言語。 .codexspec/config.yml で設定する language.* の次元は、13 のサポートコード (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi) を受け付け、LLM がその場で翻訳します。正確な一覧はプロジェクト README の「Supported Languages」表を参照してください。

2 つのセットは重なる部分もありますが同一ではありません。ドキュメントサイトには zh-TW/ru/it/ar/hi のロケールはなく、CLI は MkDocs がフォルダ名として使う zh/de/... のような素のコードを使いません。

CodexSpec のドキュメントサイトは、MkDocs と mkdocs-i18n プラグインを使って 8 言語をサポートしています。

サポートされている言語

コード 言語
en English (デフォルト)
zh 中文简体
ja 日本語
ko 한국어
es Español
fr Français
de Deutsch
pt-BR Português (Brasil)

ディレクトリ構造

docs/
├── en/                 # 英語 (ソース)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # 中国語訳
├── ja/                 # 日本語訳
├── ko/                 # 韓国語訳
├── es/                 # スペイン語訳
├── fr/                 # フランス語訳
├── de/                 # ドイツ語訳
└── pt-BR/              # ポルトガル語 (ブラジル) 訳

ドキュメントの翻訳 (メンテナー限定)

注: /codexspec:translate-docs と /codexspec:check-i18n-semantics コマンドは CodexSpec メンテナー向けのツール です。これらはこのリポジトリの MkDocs i18n のレイアウト (docs/{lang}/) と、リポジトリ内のみの用語集 docs/i18n/glossary.yml に強く結びついています。codexspec init でユーザープロジェクトに配布されることはなく、ユーザー向けのスラッシュコマンドとしては利用できません。

CodexSpec 自体に取り組む場合、これらのコマンドは .claude/commands/codexspec/ に置かれ、他のスラッシュコマンドと同じように呼び出します。自身のプロジェクトドキュメントを翻訳するエンドユーザーは、Claude を直接使い、好みのワークフローで行ってください。

CodexSpec メンテナー向けに、/codexspec:translate-docs コマンドでドキュメントを翻訳します。

# 中国語に翻訳
/codexspec:translate-docs --lang zh

# 特定のファイルを日本語に翻訳
/codexspec:translate-docs user-guide/installation.md --lang ja

# 差分翻訳 (変更されたファイルのみ)
/codexspec:translate-docs --lang ko --incremental

# プレビューモード (ファイルを変更しない)
/codexspec:translate-docs --lang es --dry-run

翻訳用語集

docs/i18n/glossary.yml (リポジトリ内のみ) の用語集は、CodexSpec 自体のドキュメントを翻訳する際の用語の一貫性を担保します。

version: "1.0"

# 英語のまま保持する用語
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# 一般的な用語の訳
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# 特例のためのスマートルール
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

翻訳の方法論

翻訳は、英語を単語通り当てはめたものではなく、それぞれの言語で自然に読めることを目指します。

  • 意味を第一に。 各パッセージが伝える内容をとらえ、対象言語自身の表現と文構造で再表現します。
  • 英語のままが明快な場合は維持。 適切な母語訳がない、あるいは英語の方が認知されやすい技術用語は、無理に訳さず英語のままにします。たとえば "AI coding agent" は "AI 编程助手" のような自然な母語表現にし、硬直した直訳にはしません。
  • 母語としての自然さ。 最初からその言語で書かれたかのように読める文章を目指します。

品質チェック

構造チェック

すべての言語ディレクトリが同じファイル構造を持つかを検証します。

./scripts/bash/check-i18n-structure.sh

完全性チェック

翻訳に未翻訳の英語が残っていないかを検出します。

./scripts/bash/check-i18n-completeness.sh

意味チェック (メンテナー限定)

AI による意味的一貫性分析。内部コマンド経由で CodexSpec メンテナーが利用できます (上記のメンテナー限定の注記を参照)。

/codexspec:check-i18n-semantics --lang zh

CI/CD 連携

.github/workflows/docs-i18n.yml ワークフローは ビルドゲートとしてのみ機能 します。docs/** や mkdocs.yml の変更があるたびに (main への push とプルリクエストで) すべての言語に対して mkdocs build --strict を実行し、ビルドエラー・リンク切れ・不正なコンテンツを捕捉します。翻訳自体は行いません。

翻訳は /codexspec:translate-docs (上記参照) を使って手作業で生成・コミットされ、英語ソースと全翻訳が 1 つのレビューされたアトミックコミットに入ります。CI での自動翻訳は意図的に削除されました。かつてのジョブは実際には走っておらず (不正な if でスキップされていた)、常設の API キーを必要とし、レビューされていない翻訳を main に直接コミットするおそれがありました。

利点

  • 翻訳のメンテナンス負荷ゼロ: 複数のテンプレート版を維持する必要がない
  • 常に最新: テンプレートの更新が即座に全言語に行き渡る
  • コンテキスト対応: 技術用語は適切な場合に英語のまま保持
  • 自動化された品質: CI が翻訳の一貫性を担保
  • AI 支援: Claude がコンテキストを踏まえた翻訳を提供