設定

Rosettaはゼロコンフィグで動作します。プロジェクトからロケールファイル、フォーマット、ターゲット言語を自動検出します。より詳細な制御を行うには、プロジェクトのルートに i18n-rosetta.config.json を作成するか、以下を実行します。

npx i18n-rosetta init

完全な設定リファレンス

i18n-rosetta.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "defaultMethod": "llm",
  "batchSize": 80,
  "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"`	ロケールファイルへのパス。Rosettaはこのディレクトリをスキャンします。
`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` を使用し (例: `google/gemini-3.5-flash`)、直接のプロバイダーはそのままの名前を使用します (例: `gpt-4o`、`gemini-2.5-flash`)。
`defaultMethod`	`string`	`"llm"`	デフォルトの翻訳メソッド: `llm`、`llm-coached`、`google-translate`、`deepl`、`microsoft-translator`、`libretranslate`、`openai`、`anthropic`、`gemini`、`api`。`--method` CLIフラグによって上書きされます。
`batchSize`	`number`	`80`	翻訳バッチあたりのキー数。大きいほどAPI呼び出しは減りますが、プロンプトは大きくなります。
`jsonConcurrency`	`number`	`200`	JSONキー同期におけるロケール翻訳の最大並列数。`--json-concurrency` CLIフラグによって上書きされます。
`contentConcurrency`	`number`	`48`	コンテンツ (Markdown/MDX) 翻訳におけるAPI呼び出しの最大並列数。`--content-concurrency` CLIフラグによって上書きされます。
`fallbackPrefix`	`string`	`"[EN] "`	以前の実行から残っている未翻訳のレガシー値を検出するために `audit` および `verify` が使用するマーカープレフィックス。Rosettaはこのプレフィックスを書き込まず、検出のために読み取るだけです。
`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`	インストールされたプラグインの名前 (`.rosetta/methods/` から)
`model`	`string`	このペアのデフォルトモデルを上書きします
`endpoint`	`string`	リモートAPIエンドポイントURL。`method` が `api` の場合に必須です。
`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."
  }
}

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

完全な設定を持つオブジェクト

{
  "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`) またはカスタムテキストを指定できます。Language Cards を参照してください。
`name`	`string`	人間が読める言語名 (ステータス表示用)
`model`	`string`	デフォルトモデルを上書きします
`batchSize`	`number`	デフォルトのバッチサイズを上書きします
`maxRetries`	`number`	失敗したバッチの最大再試行回数 (デフォルト: 3)
`script`	`string`	ISO 15924スクリプトコード。品質ゲートでのスクリプト検証をトリガーします。

:::info 継承チェーン設定は以下の順序で解決されます (最初のものが優先されます)。

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

たとえば、pairs["en:fr"] が model を設定している場合、言語レベルとグローバルの両方の model の値を上書きします。 :::

英語以外のソース

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

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

i18n-rosetta.config.json (permanent)
{
  "inputLocale": "fr"
}

ロックファイル

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

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

`.rosettaignore`

プロジェクトのルートに .rosettaignore を作成して、lint のスキャンからファイルを除外します。.gitignore のようにglobパターンを使用します。

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

`.rosetta/` ディレクトリ

Rosettaは内部状態を保持するために、プロジェクトのルートに .rosetta/ ディレクトリを作成します。これはプロジェクトのソースではなくローカルの最適化であるため、通常はこれを .gitignore に追加する必要があります。

.rosetta/

ファイル	目的	コミット?
`tm.json`	翻訳メモリキャッシュ — ソーステキスト + ロケール + メソッドをキーとして以前の翻訳を保存します	いいえ (ローカルキャッシュ)
`xliff/*.xliff`	プロの翻訳者がレビューするためのXLIFFエクスポートファイル	いいえ (一時的)
`methods/`	インストールされたメソッドプラグインのマニフェスト	はい (共有設定)
`backups/`	ラップ前のバックアップ (`wrap --undo` によって作成)	いいえ (セーフティネット)

tm.json の詳細と、それがどのようにAPIコストを節約するかについては、Translation Memory を参照してください。

プログラマティックAPI

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

import { GeminiMethod, runSync, resolveConfig } from 'i18n-rosetta';

// 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 'i18n-rosetta';

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() ヘルパーを使用してください。

完全な設定リファレンス​

フィールド​

ペア設定​

ペアフィールド​

言語設定​

コードの配列 (最もシンプル)​

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

完全な設定を持つオブジェクト​

言語フィールド​

英語以外のソース​

ロックファイル​

.rosettaignore​

.rosetta/ ディレクトリ​

プログラマティックAPI​

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

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

関連項目​