設定

Champollion はゼロ設定で動作します。プロジェクトからロケールファイル、フォーマット、翻訳先言語を自動検出します。より細かく制御したい場合は、プロジェクトルートに champollion.config.json を作成するか、次のコマンドを実行してください：

npx champollion init

設定リファレンス（全項目）

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note typegen は未実装です typegen 設定ブロックは設定ローダーによって認識・保持されますが、TypeScript の型生成はまだ実装されていません。これは将来実装予定の機能のプレースホルダーです。現時点ではこれらの値を設定しても効果はありません。 :::

フィールド

フィールド	型	デフォルト	説明
`version`	`number`	`3`	設定スキーマのバージョン。常に `3` を指定します。
`inputLocale`	`string`	`"en"`	ソース言語コード（BCP 47）。
`localesDir`	`string`	`"./locales"`	ロケールファイルへのパス。Champollion はこのディレクトリをスキャンします。
`contentDir`	`string`	`null`	Hugo のコンテンツディレクトリ。Markdown 本文の翻訳を有効にします。
`translatableFields`	`string[]`	`null`	コンテンツ翻訳で使用する翻訳可能なフロントマターフィールドのデフォルトを上書きします。`null` の場合は組み込みのデフォルト（`title`、`description`、`summary`）を使用します。
`format`	`string`	`"auto"`	ファイルフォーマット：`json`、`toml`、`yaml`、または `auto`（拡張子から自動検出）。
`model`	`string`	`"google/gemini-3.5-flash"`	LLM メソッドのデフォルトモデル。OpenRouter のフルスラッグ（`provider/model`）または `shared/model-aliases.json` の短縮エイリアス（例：`gemini-flash`）を指定できます。直接プロバイダーの場合はベア名を使用します（例：`gpt-4o`）。
`temperature`	`number`	`0.3`	LLM の temperature（0.0〜2.0）。低いほど決定論的になります。
`defaultMethod`	`string`	`"llm"`	デフォルトの翻訳メソッド：`llm`、`llm-coached`、`google-translate`、`deepl`、`microsoft-translator`、`libretranslate`、`openai`、`anthropic`、`gemini`、`api`。`--method` CLI フラグで上書きできます。
`batchSize`	`number`	`80`	翻訳バッチあたりのキー数。大きいほど API 呼び出し回数は減りますが、プロンプトが長くなります。
`coachingFile`	`string`	`null`	フリーテキストのコーチングプロンプトファイルへのパス（プロジェクトルートからの相対パス）。起動時に内容が読み込まれ、`Coaching guidance:` ブロックとしてシステムプロンプトに挿入されます。
`promptContext`	`string`	`null`	システムプロンプトに挿入するアプリケーションのコンテキスト文字列（例：「E コマースの商品説明」）。モデルがドメインに合わせた翻訳を行うのに役立ちます。
`jsonConcurrency`	`number`	`200`	JSON キー同期における並列ロケール翻訳の最大数。`--json-concurrency` CLI フラグで上書きできます。
`contentConcurrency`	`number`	`48`	コンテンツ（Markdown/MDX）翻訳における並列 API 呼び出しの最大数。`--content-concurrency` CLI フラグで上書きできます。
`fallbackPrefix`	`string`	`"[EN] "`	`audit` および `verify` が過去の実行で未翻訳のまま残った値を検出するために使用するマーカープレフィックス。Champollion はこのプレフィックスを書き込まず、検出のためにのみ読み取ります。
`apiKeyEnvVar`	`string`	`"OPENROUTER_API_KEY"`	API キーの環境変数名。カスタムの環境変数名を使用する場合に上書きします。
`baseUrl`	`string`	`""`	SEO アーティファクト生成（hreflang、サイトマップ、JSON-LD）のベース URL。
`pairs`	`object`	`{}`	ペアごとのメソッド、モデル、品質の上書き設定。ペア設定を参照してください。
`languages`	`object`	`{}`	言語ごとの上書き設定。言語設定を参照してください。
`lint.srcDir`	`string`	`null`	lint スキャンのソースディレクトリ。`null` の場合はフレームワークから自動検出します。
`lint.ignore`	`string[]`	`["node_modules", ...]`	lint から除外する glob パターン。
`lint.minLength`	`number`	`2`	ハードコードされた文字列としてフラグを立てる最小文字列長。
`seo.urlPattern`	`string`	`"/:locale/:path"`	hreflang タグ生成用の URL パターンテンプレート。
`seo.pages`	`string[]`	`null`	SEO 用の明示的なページリスト。`null` の場合はロケールキーから自動検出します。
`typegen.output`	`string`	`null`	生成する TypeScript 型の出力パス。`null` の場合は無効です。
`typegen.autoGenerate`	`boolean`	`false`	各同期後に型を自動再生成します。

ペア設定

ソース→ターゲットの各ペアを個別に設定できます：

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

ペアフィールド

フィールド	型	説明
`method`	`string`	翻訳メソッド：`llm`、`llm-coached`、`google-translate`、`deepl`、`microsoft-translator`、`libretranslate`、`openai`、`anthropic`、`gemini`、`api`
`methodPlugin`	`string`	インストール済みプラグインの名前（`.champollion/methods/` から）
`model`	`string`	このペアのデフォルトモデルを上書きします
`temperature`	`number`	このペアのデフォルト temperature を上書きします
`batchSize`	`number`	このペアのデフォルトバッチサイズを上書きします
`register`	`string`	レジスター／トーンの上書き（プリセットキーまたは自由記述テキスト）
`endpoint`	`string`	リモート API エンドポイントの URL。`method` が `api` の場合に必須です。
`coachingFile`	`string`	このペア用のコーチングプロンプトファイルへのパス
`promptContext`	`string`	このペアのアプリケーションコンテキスト
`qualityTier`	`string`	表示ティア：`standard`、`high`、`research`、`verified`

言語設定

言語は3つの形式で指定できます：

コードの配列（最もシンプル）

{
  "languages": ["fr", "de", "ja"]
}

各言語は組み込みのレジスターテーブルからデフォルトのレジスターを取得します。デフォルトが存在しない言語には "Professional register." が適用されます。

レジスター文字列を持つオブジェクト

値には言語カードのプリセットキーまたはカスタムレジスターテキストを指定できます：

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Champollion は文字列が言語カードのプリセットキーと一致するかどうかを確認します。一致する場合はカードのフルレジスタープロンプトが使用され、一致しない場合は文字列がそのまま使用されます。利用可能なプリセットについてはサポート言語を参照してください。

フル設定を持つオブジェクト

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

同じブロック内で短縮形とフルオブジェクトを混在させることができます。

言語フィールド

フィールド	型	説明
`register`	`string`	スタイル／トーンの指示。プリセットキー（例：`casual-tu`、`formal-hapsyo`）またはカスタムテキストを指定できます。言語カードを参照してください。
`name`	`string`	人間が読める言語名（ステータス表示用）
`model`	`string`	デフォルトモデルを上書きします
`temperature`	`number`	デフォルト temperature を上書きします
`batchSize`	`number`	デフォルトバッチサイズを上書きします
`coachingFile`	`string`	この言語用のコーチングプロンプトファイルへのパス
`promptContext`	`string`	この言語のアプリケーションコンテキスト
`maxRetries`	`number`	失敗したバッチの最大リトライ回数（デフォルト：3）
`script`	`string`	ISO 15924 スクリプトコード。品質ゲートでのスクリプト検証を有効にします。

:::info 継承チェーン設定は次の順序で解決されます（先に見つかったものが優先されます）：

ペアレベル → 言語レベル → グローバル設定 → デフォルト

たとえば、pairs["en:fr"] で model を設定すると、言語レベルおよびグローバルの model の値の両方が上書きされます。 :::

英語以外のソース言語

ソース言語が英語でない場合：

# CLI flag (one-time)
npx champollion sync --source fr

champollion.config.json (permanent)
{
  "inputLocale": "fr"
}

ロックファイル

Champollion は .champollion.lock を作成し、翻訳済みソース値の SHA-256 ハッシュを追跡します。すべての開発者が同じ翻訳ベースラインを共有できるよう、このファイルをコミットしてください。

ソース値が変更されるとハッシュが一致しなくなり、次の同期時に Champollion がそのキーを再翻訳します。

`.champollionignore`

lint スキャンからファイルを除外するには、プロジェクトルートに .champollionignore を作成します。.gitignore と同様に glob パターンを使用します：

.champollionignore
src/components/legacy/**
src/utils/constants.js
**/*.test.js

`.champollion/` ディレクトリ

Champollion はプロジェクトルートに .champollion/ ディレクトリを作成し、内部状態を管理します。これはプロジェクトのソースではなくローカルの最適化用データであるため、通常は .gitignore に追加することを推奨します：

.champollion/

ファイル	用途	コミット対象
`tm.json`	翻訳メモリキャッシュ — ソーステキスト・ロケール・メソッドをキーとして過去の翻訳を保存します	不要（ローカルキャッシュ）
`xliff/*.xliff`	プロの翻訳者によるレビュー用 XLIFF エクスポートファイル	不要（一時ファイル）
`methods/`	インストール済みメソッドプラグインのマニフェスト	必要（共有設定）
`backups/`	ラップ前のバックアップ（`wrap --undo` によって作成）	不要（安全網）

tm.json の詳細および API コストの節約方法については、翻訳メモリを参照してください。

プログラマティック API

ビルドスクリプトやカスタム統合では、パッケージから直接インポートできます：

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

利用可能なエクスポート

エクスポート	機能
`TranslationMethod`	すべてのメソッドの基底クラス
`LLMMethod`	LLM メソッドの基底クラス（OpenRouter）
`DirectLLMMethod`	直接 LLM プロバイダーの基底クラス（OpenAI、Anthropic、Gemini）
`OpenAIMethod`、`AnthropicMethod`、`GeminiMethod`	直接 LLM プロバイダークラス
`DeepLMethod`、`MicrosoftTranslatorMethod`、`LibreTranslateMethod`	従来の MT クラス
`GoogleTranslateMethod`	Google Cloud Translation
`LLMCoachedMethod`	コーチング付き LLM（OpenRouter + コーチングデータ）
`APIMethod`	リモート API クライアント
`runSync`、`runContentSync`	フル同期パイプライン
`resolveConfig`、`resolvePairs`	設定解決
`validateTranslations`	品質ゲート
`loadCoachingData`、`findDictionaryMatches`	コーチングユーティリティ

カスタムプロバイダーの拡張

DirectLLMMethod を拡張することで、約40行で新しい LLM プロバイダーを追加できます：

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

翻訳、コーチング、リトライループ、モデル検証、品質ティア、セットアップヘルプがすぐに利用できます。プロバイダー固有の実装が必要なのは HTTP リクエストの形式のみです。生の fetch() を使用する非 LLM アダプターの場合は、独自のリトライループを実装する代わりに、lib/methods/fetch-with-retry.js の共有ヘルパー fetchWithRetry() を使用してください。

設定リファレンス（全項目）​

フィールド​

ペア設定​

ペアフィールド​

言語設定​

コードの配列（最もシンプル）​

レジスター文字列を持つオブジェクト​

フル設定を持つオブジェクト​

言語フィールド​

英語以外のソース言語​

ロックファイル​

.champollionignore​

.champollion/ ディレクトリ​

プログラマティック API​

利用可能なエクスポート​

カスタムプロバイダーの拡張​

関連情報​