クックブック：30言語の翻訳

プロジェクトを少数のロケールからグローバルなカバレッジへとスケールアップします。このクックブックでは、実際の多言語デプロイメントにおける手法の選択、コスト最適化、CI統合について説明します。

シナリオ： en、fr、es を持つ SaaS アプリがあります。品質要件の異なる3つの階層にわたって、さらに27言語を追加する必要があります。

ステップ1：言語を分類する

30言語すべてに同じアプローチが必要なわけではありません。利用可能な手法の品質によってグループ分けします。

階層	言語	手法	理由
Tier 1 — プレミアム	`ja`、`ko`、`zh`、`de`、`pt`	`llm` (GPT-4o)	高価値市場、複雑な文法
Tier 2 — スタンダード	`it`、`nl`、`pl`、`sv`、`da`、`fi`、`no`、`cs`、`ro`、`hu`、`el`、`tr`、`id`、`ms`、`th`、`vi`、`uk`、`bg`	`google-translate`	大量処理向け、Google による充実したサポート
Tier 3 — コーチング付き	`crk`、`oj`、`mi`、`haw`	`llm-coached` + プラグイン	低リソース言語、用語の統一が必要

ステップ2：言語ペアごとに設定する

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

注意： pairs に記載されていない言語は defaultMethod: "google-translate" を継承します。30言語すべてを列挙する必要はありません。

情報

crk のサポートは開発中です。ステータスおよびコントリビューションのガイドラインについては、低リソース言語のサポートをご覧ください。

ステップ3：API キーを設定する

この設定には両方の API キーが必要です。

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

ステップ4：まずドライランを実行する

30言語を翻訳する前に、必ずプレビューを確認してください。

npx champollion sync --dry

出力を確認します。以下の情報が表示されます。

各ペアで使用される手法
ロケールごとに新規・変更されたキーの数
階層ごとの推定 API 呼び出し回数

ステップ5：同期を実行する

npx champollion sync

Champollion は各ペアを独立して処理します。Google Translate を使用する Tier 2 のペアは高速です。Tier 1 の LLM ペアは低速ですが、品質は高くなります。Tier 3 のコーチング付きペアはプラグインのコーチングデータを使用します。

差分更新

初回の同期後、以降の実行では変更または追加されたキーのみが翻訳されます。

# Only keys that changed since last sync
npx champollion sync

ロックファイル（.champollion.lock）が翻訳済みの内容を追跡するため、安定したコンテンツが再翻訳されることはありません。

ステップ6：品質を確認する

すべての言語ペアのステータスを確認します。

npx champollion status

各ペアの手法、モデル、品質階層、コーチングデータやベンチマークスコアの有無を示すテーブルが出力されます。

出力はレジスターの指定を反映していますか？

ステップ2では言語ごとにレジスターを指定しました。日本語には "Polite/formal"、ドイツ語には "Formal (Sie)" といった具合です。（この用語が初めての方は、用語集でわかりやすく説明しています。）これらの指示は翻訳プロンプトに組み込まれますが、プロンプトはあくまでリクエストであり、保証ではありません。

MT Eval Arena ハーネス（公開リーダーボードを支えているツールと同じもの）を使用すると、翻訳のサンプルに対してレジスターとスタイルの遵守度を測定できます。文体メトリクスは、各出力を期待されるレジスター（フォーマル・インフォーマルのマーカー、T–V 代名詞、短縮形、文長のずれ）と照合し、実行全体の style_consistency_rate を報告します。--style-profile を使用してカスタムのブランドボイスプロファイルを指定することもできます。

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

正直に2点お断りしておきます。これらのメトリクスは参考情報です（リーダーボードの総合スコアには含まれません）。また、フォーマリティ検出はマーカーベースであり、ずれを検出するものであって、人間による判断ではありません。詳細とメトリクスの定義については、文体・レジスターメトリクスをご覧ください。

ステップ7：CI に統合する

プッシュのたびに翻訳を最新の状態に保つため、GitHub Actions ワークフローに以下を追加します。

.github/workflows/i18n-sync.yml
name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx champollion sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

コスト試算

500個のソースキーを30言語に翻訳するプロジェクトの場合：

階層	言語	手法	概算コスト
Tier 1（5言語）	ja, ko, zh, de, pt	GPT-4o	〜$2.50 / フル同期
Tier 2（18言語）	it, nl, pl など	Google Translate	〜$0.90 / フル同期
Tier 3（4言語）	crk, oj, mi, haw	GPT-4o-mini コーチング付き	〜$0.40 / フル同期
合計	30言語	混合	〜$3.80 / フル同期

差分同期（変更キー5〜20件）のコストはフル同期のわずかな割合に収まります。

ステップ1：言語を分類する​

ステップ2：言語ペアごとに設定する​

ステップ3：API キーを設定する​

ステップ4：まずドライランを実行する​

ステップ5：同期を実行する​

差分更新​

ステップ6：品質を確認する​

出力はレジスターの指定を反映していますか？​

ステップ7：CI に統合する​

コスト試算​

関連情報​