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

エージェントガイド: i18n-rosettaの使い方

i18n-rosettaは、アプリのロケールファイルを1つのコマンドで翻訳するCLIツールです。このガイドは、ゼロから素早くロケールファイルの翻訳を行いたいAIエージェント（またはAIエージェントと連携する開発者）向けに作成されています。

:::tip すでに使い慣れている場合 コマンドだけが必要な場合は、CLIリファレンスにジャンプしてください。翻訳メソッドを構築してベンチマークを行いたい場合は、Arenaエージェントガイドを参照してください。 :::

環境セットアップ​

# No global install needed — npx runs it directly
npx i18n-rosetta sync

要件:

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

APIキーのセットアップ — 使用するメソッドに応じて、rosettaには少なくとも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

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

初回同期​

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

npx i18n-rosetta sync

実行される処理:

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

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

設定​

プロジェクトのルートにi18n-rosetta.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-translateGT（Google翻訳）がうまく機能するリソースが豊富な言語20ドル/100万文字GOOGLE_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"
ハルシネーションループトライグラム（3文字/3単語）の繰り返し"Qo' Qo' Qo' Qo'"
長さの膨張出力がソースの4倍以上の長さになっている10文字のソース → 50文字の出力
文字体系の準拠ロケールに対して誤った文字体系（スクリプト）が使われているアラビア語ロケールに対するラテン文字

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

詳細: 品質ゲート

翻訳メモリ​

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

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

1回の実行でキャッシュをバイパスする場合: npx i18n-rosetta sync --no-tm

詳細: 翻訳メモリ

生成されるファイル​

Rosettaはプロジェクト内にいくつかのファイルを作成します。誤って削除したり、間違ったファイルをコミットしたりしないように、それぞれの役割を把握しておいてください:

ファイル目的Git?
.i18n-rosetta.lock翻訳されたソース値のSHA-256ハッシュ（変更検出用）はい — コミットしてください
.i18n-rosetta-content.lock同上（Markdown/MDXコンテンツファイル用）はい — コミットしてください
.rosetta/tm.json翻訳メモリのキャッシュはい — コミットしてください（チームのAPIコストを節約します）
.rosetta/coaching/コーチングデータのディレクトリはい — これはあなたの言語知識です
i18n-rosetta.config.jsonプロジェクト設定はい — コミットしてください

一般的なパターン​

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

npx i18n-rosetta sync --pair en-fr

設定されたすべてのペアを翻訳する:

npx i18n-rosetta sync

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

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

npx i18n-rosetta sync --content

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

ドライラン（書き込まずにプレビュー）:

npx i18n-rosetta sync --dry-run

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

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

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

npx i18n-rosetta sync --force-content

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

npx i18n-rosetta status

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

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

npx i18n-rosetta 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を使用します
ロックファイルの競合.i18n-rosetta.lockはSHA-256ハッシュを使用しています。マージコンフリクトはどちらかのバージョンを保持して解決し、その後同期を再実行すれば安全です

次のステップ​