トラブルシューティング

i18n-rosettaの一般的な問題と解決策です。

APIと認証

"OPENROUTER_API_KEY not found"

RosettaでLLM翻訳を行うにはAPIキーが必要です。環境変数として設定してください：

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

または、.envファイルに設定します（プロジェクトで.envファイルを読み込む場合）：

OPENROUTER_API_KEY=sk-or-v1-...

ヒント

Google Translate APIキーのみをお持ちの場合、rosettaは自動的にそれを検出し、デフォルトのメソッドとしてGoogle Translateを使用します。設定の変更は必要ありません。

OpenRouterからの"401 Unauthorized"

APIキーが無効であるか、期限切れです。openrouter.ai/keysで確認してください。

"429 Too Many Requests" / レート制限

Rosettaは、指数的バックオフを使用して内部的にレート制限を処理します。頻繁にレート制限に引っかかる場合は、以下の対策をお試しください：

設定でバッチサイズを小さくする：
```
{ "batchSize": 15 }
```
レート制限の上限が高いモデルを使用する（例：google/gemini-3.5-flashは制限が緩やかです）
大量の翻訳ペアには、より安価で高速なメソッドを使用する — Google Translateにはレート制限がありません：
```
{ "pairs": { "en:it": { "method": "google-translate" } } }
```

モデルが見つからない / 404エラー

直接LLMプロバイダー（openai、anthropic、gemini）は、初回使用時にモデルの文字列を検証します。以下の警告が表示された場合：

"looks like an OpenRouter path" — 直接プロバイダーでOpenRouter形式のモデル（google/gemini-3.5-flash）を使用しています。直接プロバイダーでは、モデル名のみを使用します：

- { "method": "gemini", "model": "google/gemini-3.5-flash" }
+ { "method": "gemini", "model": "gemini-2.5-flash" }

または、llmメソッドに切り替えてOpenRouterを使用します：

{ "method": "llm", "model": "google/gemini-3.5-flash" }

"is an Anthropic/OpenAI/Gemini model" — 誤ったプロバイダーにモデルを送信しています：

- { "method": "gemini", "model": "claude-sonnet-4-6" }
+ { "method": "anthropic", "model": "claude-sonnet-4-6" }

"not found in available models" — モデルが非推奨になっているか、スペルが間違っている可能性があります。Rosettaはプロバイダーの最新のモデルリストを取得し、代替案を提案します。現在のモデル名については、プロバイダーのドキュメントを確認してください。

:::tip モデルの非推奨化についてプロバイダーは定期的にモデル名を廃止します。プロバイダーのアップデート後に翻訳が突然失敗するようになった場合は、[WARN]の出力を確認してください。現在の代替モデルが表示されます。 :::

翻訳の品質

翻訳がソース言語のままになる

これは品質ゲートで検出されます。翻訳が英語のソースと完全に一致する場合、拒否されて再試行されます。この問題が続く場合は、以下の対策をお試しください：

モデルを確認する — 一部のモデルは特定の言語ペアでパフォーマンスが低下します
トーンや文体の指示を追加する — どの言語で出力するかをモデルに指示します：
```
{
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal Japanese" }
  }
}
```
別のモデルを試す — gpt-4o-miniからgpt-4oまたはgoogle/gemini-2.5-proに切り替えます

誤った文字体系の出力（例：日本語に対してラテン文字が出力される）

品質ゲートの文字体系コンプライアンスチェックにより、ほとんどのケースは検出されます。この問題が続く場合は、以下の対策をお試しください：

ロケールコードが正しいか確認する（jpではなくja）
registerフィールドに明示的な文字体系の指示を追加する：
```
{ "register": "Japanese using hiragana, katakana, and kanji" }
```

出力におけるハルシネーションのパターン

繰り返されるトライグラムのパターン（例："hello hello hello"）は、ハルシネーションループ検出器によって検出されます。出力が文字化けしているにもかかわらず検出器を通過してしまう場合は、以下の対策をお試しください：

バッチサイズを小さくする — バッチサイズを小さくすると、より焦点の絞られた出力が得られます
より強力なモデルを使用する — 大規模なモデルほど、非ラテン文字でのハルシネーションが少なくなります
コーチングデータを追加する — 辞書の用語が翻訳の基準となります

ファイルとフォーマットの問題

"No locale files found"

Rosettaはロケールファイルを自動検出します。見つからない場合は、以下の対策をお試しください：

localesDirを確認する — ロケールファイルが含まれるディレクトリを指定する必要があります：
```
{ "localesDir": "./locales" }
```
ファイル名を確認する — ファイル名はロケールコードにする必要があります：en.json、fr.jsonなど
フォーマットを確認する — サポートされているフォーマット：JSON、ネストされたJSON、YAML、TOML

ロックファイルの競合

.i18n-rosetta.lockが不正な状態になった場合：

# Reset the lock file (next sync will retranslate everything)
rm .i18n-rosetta.lock
npx i18n-rosetta sync

警告

ロックファイルを削除すると、次回の同期時に変更されたキーだけでなく、すべてのキーが再翻訳されます。大規模なプロジェクトではAPIコストに影響を与えるため注意してください。

特定のキーの再翻訳

個別の翻訳が間違っており、ロックファイルを削除せずに強制的に再翻訳したい場合：

# Re-translate a single key
npx i18n-rosetta sync --force-keys "hero.title"

# Re-translate multiple keys
npx i18n-rosetta sync --force-keys "nav.home,nav.about,footer.copyright"

--force-keysフラグは、指定した特定のキーに対するロックファイルのハッシュチェックを上書きし、他のキーに影響を与えることなく強制的に再翻訳を行います。

コンテンツの翻訳によってコードブロックが破損する

通常、この問題は発生しません（コードブロックは翻訳前に保護されます）。もし発生した場合は、以下の対策をお試しください：

コードブロックが標準のフェンシング（3つのバッククォート）を使用しているか確認する
ソースのMarkdownに閉じられていないコードブロックがないか確認する
イシューを報告する — これはセンチネル保護システムのバグです

CLIの問題

`--watch`が変更を検出しない

ファイルの監視にはNode.jsネイティブのfs.watchを使用しています。既知の問題は以下の通りです：

ネットワークドライブ — NFS/SMBマウントではfs.watchが確実に動作しません
Dockerボリューム — ポーリングモードを使用するか、コンテナ内でrosettaを実行してください
大規模なディレクトリ — ウォッチャーはlocalesDirを再帰的に監視します。ツリーが非常に深い場合、OSの制限を超える可能性があります

`npx`が古いバージョンで実行される

# Clear the npx cache
npx --yes i18n-rosetta@latest sync

または、グローバルにインストールします：

npm install -g i18n-rosetta
i18n-rosetta sync

パフォーマンス

多くの言語で同期が遅い

Rosettaはデフォルトですべてのロケールを並行して翻訳します。それでも同期が遅い場合は、以下の対策をお試しください：

大量の翻訳ペアにはGoogle Translateを使用する — LLM翻訳よりも10〜50倍高速です
バッチサイズを大きくする（デフォルトは80）：
```
{ "batchSize": 120 }
```
並行処理を調整する — JSONロケールの並行処理はデフォルトで200、コンテンツは48です。APIプロバイダーがより高いレート制限をサポートしている場合：
```
npx i18n-rosetta sync --json-concurrency 80 --content-concurrency 20
```
高速なモデルを使用する — gpt-4o-miniはgpt-4oよりも大幅に高速です

APIコストが高い

バッチサイズを確認する — バッチサイズが大きいほどAPI呼び出し回数が減り、コストが下がります
翻訳メモリを使用する — TMはデフォルトでオンになっています。i18n-rosetta tm statsを実行して機能しているか確認してください。複数回同期してもエントリが0の場合は、.rosetta/ディレクトリの権限に問題がある可能性があります
プロンプトキャッシングを使用する — Rosettaは、AnthropicおよびGoogleのモデルでキャッシュヒット率を上げるために、システムメッセージとユーザーメッセージを分割します
Tier 2の言語にはGoogle Translateを使用する — 30言語の翻訳のクックブックを参照してください

プロバイダー切り替え後の古い翻訳

ある翻訳メソッドから別のメソッド（例：llmからdeepl）に切り替えた場合、ソーステキストが変更されていないキーに対しては、TMキャッシュが以前のメソッドの古い翻訳を引き続き提供する可能性があります。キャッシュキーにはメソッド名が含まれているため、ほとんどのケースは自動的に処理されます。ただし、同じメソッド内でmodelを変更した場合：

# Force fresh translations for all keys
i18n-rosetta sync --no-tm

# Or clear the cache entirely and re-sync
i18n-rosetta tm clear --yes
i18n-rosetta sync

キャッシュキーの設計の詳細については、翻訳メモリを参照してください。

まだ解決しませんか？

GitHub Issues — 既存のイシューを検索するか、新しいイシューを報告する
アーキテクチャドキュメント — システム設計を理解する
品質ゲート — 内部での検証の仕組み

APIと認証​

"OPENROUTER_API_KEY not found"​

OpenRouterからの"401 Unauthorized"​

"429 Too Many Requests" / レート制限​

モデルが見つからない / 404エラー​

翻訳の品質​

翻訳がソース言語のままになる​

誤った文字体系の出力（例：日本語に対してラテン文字が出力される）​

出力におけるハルシネーションのパターン​

ファイルとフォーマットの問題​

"No locale files found"​

ロックファイルの競合​

特定のキーの再翻訳​

コンテンツの翻訳によってコードブロックが破損する​

CLIの問題​

--watchが変更を検出しない​

npxが古いバージョンで実行される​

パフォーマンス​

多くの言語で同期が遅い​

APIコストが高い​

プロバイダー切り替え後の古い翻訳​

まだ解決しませんか？​