メインコンテンツへスキップ

エージェントガイド：champollion の使い方

champollion は、1つのコマンドでアプリのロケールファイルを翻訳する CLI ツールです。このガイドは、ゼロから翻訳済みロケールファイルを素早く作成したい AI エージェント（または AI エージェントと協働する開発者）を対象としています。

:::tip すでに使い慣れている方へ コマンドだけ確認したい場合は CLI リファレンス をご覧ください。翻訳メソッドのビルドとベンチマークを行いたい場合は Arena エージェントガイド をご覧ください。 :::

環境のセットアップ​

# No global install needed — npx runs it directly
npx champollion sync

必要条件：

  • Node.js 18 以上
  • 翻訳プロバイダーの API キー

API キーの設定 — champollion は使用するメソッドに応じて、少なくとも1つのキーが必要です：

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion は .env を自動的に読み込みます。OpenRouter のキーは openrouter.ai/keys で取得できます。

初回の同期​

Champollion はロケールファイル、そのフォーマット（JSON、TOML、YAML、PO）、および対象言語を自動検出します：

npx champollion sync

処理の流れ：

  1. champollion.config.json を読み込む（または設定を自動検出する）
  2. ソースロケールファイルをスキャンし、ネストされたキーをフラット化する
  3. .champollion.lock（以前に翻訳された値の SHA-256 ハッシュ）と比較する
  4. キャッシュされた翻訳（翻訳メモリ）を .champollion/tm.json で確認する
  5. 設定されたメソッドを使って変更・欠落・古くなったキーのみを翻訳する
  6. すべての翻訳に対してクオリティゲート（5項目のチェック）を実行する
  7. チェックを通過した翻訳をターゲットロケールファイルに書き込む
  8. ロックファイルと翻訳メモリのキャッシュを更新する

1つのキーを変更した後の典型的な再実行では、ステップ4で142件のキーがキャッシュから提供され、ステップ5で1件のキーが翻訳されます。これが、2回目以降の同期が高速かつ低コストである理由です。

設定​

プロジェクトルートに champollion.config.json を作成します：

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

主なフィールド：

フィールド用途デフォルト
inputLocaleソース言語en
pairsソース→ターゲットのマップとメソッド設定（必須）
localesDirロケールファイルの配置場所（自動検出）
modelllm/llm-coached メソッド用の LLM モデルgoogle/gemini-2.5-flash
batchSize1回の API 呼び出しあたりのキー数80（LLM）、128（Google）
jsonConcurrencyJSON キーの並列ロケール翻訳数200
contentConcurrencyコンテンツ翻訳の並列 API 呼び出し数48

詳細リファレンス：設定

翻訳メソッド​

メソッド使用場面コスト必要な API キー
llm汎用。リソースが豊富な言語に適しているトークン単位（モデルによる）OPENROUTER_API_KEY
llm-coachedターゲット言語の文法規則や辞書がある場合トークン単位＋コーチングコンテキストOPENROUTER_API_KEY
google-translateGoogle 翻訳が有効な高リソース言語100万文字あたり $20GOOGLE_TRANSLATE_API_KEY
apiHTTP エンドポイントの背後にホストされたカスタムパイプラインサーバー側で決定なし（エンドポイント側で認証を処理）
pluginローカルにインストールされた事前パッケージ済みメソッド様々様々

詳細：翻訳メソッド

コーチングデータ​

llm-coached のペアでは、コーチングデータが明示的な言語知識によって LLM を誘導します。コーチングファイルを作成します：

coaching/fr.json
{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

ペア設定でファイルを参照します：

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

クオリティゲートは、辞書の用語が実際に出力に含まれているかを検証します。違反は [TERM] 警告としてログに記録されます。

詳細：コーチングデータ

クオリティゲート​

すべての翻訳は、ディスクに書き込まれる前に5つの自動チェックを通過します：

チェック検出内容例
空白/ブランクモデルが何も返さなかった""
ソースエコーモデルが英語の入力をそのまま返した日本語に対して "Welcome"
ハルシネーションループトライグラムの繰り返し"Qo' Qo' Qo' Qo'"
長さの膨張出力がソースの4倍以上の長さ10文字のソース → 50文字の出力
スクリプト準拠ロケールに対して誤ったスクリプトアラビア語ロケールにラテン文字のテキスト

失敗は [GATE] プレフィックス付きでログに記録されます。サイレントフォールバックはありません。翻訳が失敗した場合は、黙って受け入れられるのではなく、報告されます。

詳細：クオリティゲート

翻訳メモリ​

Champollion は翻訳を .champollion/tm.json にキャッシュします。キーはソーステキスト＋ロケール＋メソッドの組み合わせです。2回目以降の同期では、変更されていないキーはキャッシュから提供されるため、API 呼び出しもコストも発生しません。

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

1回の実行でキャッシュをバイパスするには：npx champollion sync --no-tm

詳細：翻訳メモリ

生成されるファイル​

Champollion はプロジェクト内にいくつかのファイルを作成します。誤って削除したり、不適切なファイルをコミットしたりしないよう、各ファイルの役割を把握しておいてください：

ファイル用途Git 管理
.champollion.lock翻訳済みソース値の SHA-256 ハッシュ（変更検出用）はい — コミットする
.champollion-content.lock同上（Markdown/MDX コンテンツファイル用）はい — コミットする
.champollion/tm.json翻訳メモリのキャッシュはい — コミットする（チームの API コスト削減になる）
.champollion/coaching/コーチングデータのディレクトリはい — これは言語知識のリポジトリ
champollion.config.jsonプロジェクト設定はい — コミットする

よくある使用パターン​

1つの言語ペアを翻訳する：

npx champollion sync --pair en-fr

設定済みのすべてのペアを翻訳する：

npx champollion sync

Champollion はすべてのロケールを並列で翻訳します。翻訳メモリのキャッシュにより、変更されたキーのみが API にアクセスします。

コンテンツモード（Docusaurus、Hugo などの Markdown/MDX）：

npx champollion sync --content

ロケール JSON と並行して、ドキュメント、ブログ記事、コンテンツファイルを翻訳します。並列同時実行（デフォルト：48件の同時 API 呼び出し）を使用します。--content-concurrency で調整できます。

ドライラン（書き込みなしでプレビュー）：

npx champollion sync --dry-run

特定のキーを強制的に再翻訳する：

npx champollion sync --force-keys "hero.title,nav.about"

すべてのコンテンツファイルを強制的に再翻訳する：

npx champollion sync --force-content

翻訳ステータスを確認する：

npx champollion status

各ペアのカバレッジ、品質ティア、プラグイン情報を表示します。

未翻訳のフォールバックを監査する：

npx champollion audit

翻訳が必要なすべての [EN] フォールバック値を一覧表示します。

トラブルシューティング​

問題対処法
OPENROUTER_API_KEY not setキーをエクスポートするか、プロジェクトルートの .env に追加する
No locale files found設定で localesDir を指定するか、ロケールファイルが標準的な命名規則（en.json、fr.json）に従っているか確認する
[GATE] Script compliance failedターゲットロケールに期待されるスクリプトではなくラテン文字のテキストが入っている — 別のモデルを試すか、コーチングデータを追加する
[GATE] Source echoモデルが英語をそのまま返した — コーチングデータまたは別のモデルで通常は解決できる
すべての翻訳がキャッシュされている--no-tm を付けて実行してキャッシュをバイパスするか、特定のキーには --force-keys を使用する
ロックファイルのコンフリクト.champollion.lock は SHA-256 ハッシュを使用しているため、マージコンフリクトはどちらかのバージョンを残して解決し、その後同期を再実行すれば安全に対処できる

次のステップ​