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

チュートリアル：翻訳プラグインを作成する

カスタム翻訳メソッドをゼロから構築し、ベンチマークを実施して、champollion プラグインとしてデプロイします。これは、既製の API がサポートしていない新しい言語ペアを追加するための完全なワークフローです。

作成するもの： 用語の強制適用、文法ルール、ベンチマークスコアを備えた、フォーマルなフランス語向けのコーチング翻訳プラグイン。

所要時間： 30〜45 分

前提条件：

  • champollion がインストール済みであること（npm install --save-dev champollion）
  • OpenRouter の API キー（OPENROUTER_API_KEY）
  • Python 3.10 以上（評価ハーネス用）

ステップ 1：問題を特定する​

SaaS ダッシュボードをフランス語に翻訳しているとします。デフォルトの llm メソッドは正確ではあるものの、一貫性のない翻訳を生成します：

  • 「dashboard」が「tableau de bord」になる場合と「panneau de contrôle」になる場合がある
  • 語調が tu 形式と vous 形式の間で揺れる
  • 技術用語の英語化が一貫していない

汎用的な LLM プロンプトでは対応できない、用語の強制適用とレジスター制御が必要です。

ステップ 2：コーチングデータを作成する​

言語要件をエンコードするコーチングファイルを作成します：

mkdir -p .champollion/coaching
.champollion/coaching/fr.json
{
  "grammar_rules": [
    "Always use the 'vous' form for formal register",
    "French adjectives agree in gender and number with their noun",
    "Use the present tense for UI instructions, not the imperative",
    "Preserve sentence-final punctuation style from the source"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres",
    "environment variable": "variable d'environnement",
    "webhook": "webhook",
    "API key": "clé API",
    "sign in": "se connecter",
    "sign out": "se déconnecter",
    "repository": "dépôt",
    "pull request": "demande de tirage"
  },
  "style_notes": "Formal technical French. Prefer native French terms over anglicisms where established equivalents exist. Keep UI labels concise — 3 words maximum where possible."
}

各フィールドの役割：

  • grammar_rules — 明示的な制約として LLM のシステムプロンプトに注入されます
  • dictionary — ソースキーと照合され、辞書の用語が出現した場合、プロンプト内で「必須用語」として注入されます
  • style_notes — 一般的なスタイルガイダンスとしてシステムプロンプトに追記されます

ステップ 3：言語ペアを設定する​

フランス語に llm-coached を使用するよう champollion に指定します：

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "pairs": {
    "en:fr": {
      "method": "llm-coached",
      "model": "google/gemini-3.5-flash",
      "temperature": 0.2
    }
  },
  "languages": {
    "fr": {
      "register": "Formal technical French (vous-form)",
      "name": "French"
    }
  }
}

ステップ 4：テストする​

npx champollion sync --dry

ドライランの出力を確認します。以下の点をチェックしてください：

  • ✅ 辞書の用語が一貫して使用されている（「panneau de contrôle」ではなく「tableau de bord」）
  • ✅ vous 形式が全体を通じて使用されている
  • ✅ 技術用語が辞書と一致している

その後、実際の同期を実行します：

npx champollion sync

ステップ 5：評価ハーネスでベンチマークを実施する（任意）​

品質スコアが必要な場合——プラグインはベンチマークデータとともに公開されるため、必要になります——付属の評価ハーネスを使用してください。

ハーネスをインストールする​

pip install mt-eval-harness

参照コーパスを作成する​

ソース文字列と既知の良質な翻訳を含むファイルを作成します：

corpus/french-formal.json
[
  {
    "source": "Dashboard",
    "reference": "Tableau de bord"
  },
  {
    "source": "Sign in to your account",
    "reference": "Connectez-vous à votre compte"
  },
  {
    "source": "Your deployment is ready",
    "reference": "Votre déploiement est prêt"
  },
  {
    "source": "Environment variables",
    "reference": "Variables d'environnement"
  }
]

ベンチマークを実行する​

mt-eval test \
  --corpus corpus/french-formal.json \
  --source en \
  --target fr \
  --model google/gemini-3.5-flash \
  --temperature 0.2 \
  --champollion-config champollion.config.json

ハーネスは以下を出力します：

  • chrF++ — 文字レベルの F スコア（0〜100）。70 以上が優秀です。
  • BLEU — N グラムの重複度（0〜100）。コーチング翻訳では 40 以上が良好です。
  • 完全一致率 — 参照訳と完全に一致した翻訳の割合。
  • COMET — ニューラル品質指標（mt-eval setup --comet 経由でインストールした場合）。

:::tip 公開するものをテストする --champollion-config を使用すると、champollion.config.json から本番環境のモデル、レジスター、温度、コーチングデータを直接インポートします。これにより、実際にデプロイするメソッドそのものをベンチマークできます。 :::

プラグインをエクスポートする​

スコアに満足したら：

mt-eval export \
  --name french-formal-v1 \
  --report eval/logs/harness/run_report.json \
  --output ./french-formal-v1/

以下が作成されます：

french-formal-v1/
├── method.json          # Manifest with config + benchmarks
└── coaching/
    └── fr.json          # Your coaching data

ステップ 6：Champollion にプラグインをインストールする​

npx champollion plugin install ./french-formal-v1/

これにより、プラグインが .champollion/methods/french-formal-v1/ にコピーされます。

プラグインを使用するよう設定を更新します：

champollion.config.json
{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

ステップ 7：確認する​

# Check plugin is installed and shows benchmark scores
npx champollion status

# Run a sync with the plugin
npx champollion sync

# Audit licensing status
npx champollion provenance

status の出力には以下が表示されます：

en → fr
  Method:    french-formal-v1 (llm-coached)
  Model:     google/gemini-3.5-flash
  Quality:   high
  chrF++:    74.2
  BLEU:      46.8
  Exact:     42%

作成したもの​

これで以下が揃いました：

  1. コーチングデータ — 一貫性を強制する文法ルールと用語集
  2. ベンチマークスコア — プラグインとともに公開される定量的な品質指標
  3. ポータブルなプラグイン — method.json とコーチングデータをまとめた、どのマシンにもインストール可能なパッケージ
  4. 本番環境へのデプロイ — 同期パイプラインへの統合

次のステップ​