Mag-skip sa main content

Troubleshooting

Mga common issues at solutions para sa i18n-rosetta.

API & Authentication​

"OPENROUTER_API_KEY not found"​

Kailangan po ng Rosetta ng API key para sa LLM translation. I-set ito bilang environment variable:

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

O kaya sa isang .env file (kung naglo-load ang project niyo ng .env files):

OPENROUTER_API_KEY=sk-or-v1-...
tip

Kung Google Translate API key lang ang meron kayo, mag-a-auto-detect ang rosetta at gagamitin ang Google Translate bilang default method. Hindi na kailangan ng config change.

"401 Unauthorized" mula sa OpenRouter​

Invalid o expired na po ang inyong API key. I-verify ito sa openrouter.ai/keys.

"429 Too Many Requests" / Rate Limiting​

Hina-handle ng Rosetta ang rate limits internally gamit ang exponential backoff. Kung palagi kayong nakaka-hit ng rate limits:

  1. Bawasan ang batch size sa inyong config: 
    { "batchSize": 15 }
  2. Gumamit ng model na may mas mataas na rate limits (halimbawa, may generous limits ang google/gemini-3.5-flash)
  3. Gumamit ng mas mura/mabilis na method para sa high-volume pairs — walang rate limits ang Google Translate: 
    { "pairs": { "en:it": { "method": "google-translate" } } }

Model Not Found / 404 Errors​

Bina-validate ng direct LLM providers (openai, anthropic, gemini) ang inyong model string sa first use. Kung makakita kayo ng warning:

"looks like an OpenRouter path" — Gumagamit po kayo ng OpenRouter-format model (google/gemini-3.5-flash) sa isang direct provider. Gumagamit ng bare model names ang mga direct providers:

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

O kaya mag-switch sa llm method para magamit ang OpenRouter:

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

"is an Anthropic/OpenAI/Gemini model" — Nagse-send po kayo ng model sa maling provider:

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

"not found in available models" — Baka deprecated o misspelled ang model. Fini-fetch ng Rosetta ang live model list ng provider at nagsu-suggest ng alternatives. I-check ang docs ng provider para sa current model names.

:::tip Nangyayari ang model deprecation Regular na nagre-retire ng model names ang mga providers. Kung biglang mag-fail ang translations pagkatapos ng isang provider update, i-check ang [WARN] output — ipapakita nito sa inyo ang mga current alternatives. :::

Translation Quality​

Nag-e-echo sa source language ang translations​

Sinasalo ito ng quality gate. Kung identical sa English source ang translation, nire-reject ito at nire-retry. Kung mag-persist ito:

  1. I-check ang model — May mga models na poor ang performance para sa specific language pairs
  2. Magdagdag ng register instructions — Sabihin sa model kung anong language ang ipo-produce: 
    {
      "languages": {
        "ja": { "name": "Japanese", "register": "Polite/formal Japanese" }
      }
    }
  3. Subukan ang ibang model — Mag-switch mula gpt-4o-mini papuntang gpt-4o o google/gemini-2.5-pro

Wrong script output (halimbawa, Latin text para sa Japanese)​

Sinasalo ng script compliance check ng quality gate ang karamihan sa mga cases. Kung mag-persist ito:

  • I-verify kung tama ang locale code (ja, hindi jp)
  • Magdagdag ng explicit script instructions sa register field: 
    { "register": "Japanese using hiragana, katakana, and kanji" }

Hallucination patterns sa output​

Sinasalo ng hallucination loop detector ang repeated trigram patterns (halimbawa, "hello hello hello"). Kung garbled ang output pero pumasa sa detector:

  1. Bawasan ang batch size — Nagpo-produce ng mas focused na output ang smaller batches
  2. Gumamit ng mas malakas na model — Mas less mag-hallucinate ang larger models sa non-Latin scripts
  3. Magdagdag ng coaching data — Nagsisilbing anchor sa translation ang dictionary terms

File & Format Issues​

"No locale files found"​

Nag-a-auto-detect ng locale files ang Rosetta. Kung hindi nito mahanap:

  1. I-check ang localesDir — Dapat naka-point ito sa directory na naglalaman ng locale files: 
    { "localesDir": "./locales" }
  2. I-check ang file naming — Dapat naka-name ang files by locale code: en.json, fr.json, atbp.
  3. I-check ang format — Supported formats: JSON, nested JSON, YAML, TOML

Lock file conflicts​

Kung mapunta sa bad state ang .i18n-rosetta.lock:

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

Kapag dinelete po ang lock file, ibig sabihin ire-retranslate ng next sync ang lahat ng keys, hindi lang ang mga nagbago. May API cost implications po ito para sa large projects.

Pag-retranslate ng specific keys​

Kung mali ang individual translations at gusto niyo silang i-force na ma-retranslate nang hindi dine-delete ang lock file:

# 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"

Ino-override ng --force-keys flag ang lock file hash check para sa mga specific keys na iyon, kaya nafo-force ang re-translation nang hindi naaapektuhan ang ibang keys.

Nako-corrupt ng content translation ang code blocks​

Hindi po dapat ito mangyari — naka-shield ang code blocks bago ang translation. Kung mangyari man ito:

  1. I-verify kung gumagamit ng standard fencing (triple backticks) ang code block
  2. I-check kung may unclosed code blocks sa source Markdown
  3. Mag-file ng issue — bug po ito sa sentinel shielding system

CLI Issues​

Hindi nade-detect ng --watch ang changes​

Gumagamit ng Node.js native fs.watch ang file watching. Known issues:

  • Network drives — Hindi reliable na gumagana ang fs.watch sa NFS/SMB mounts
  • Docker volumes — Gumamit ng polling mode o i-run ang rosetta sa loob ng container
  • Large directories — Minomonitor ng watcher ang localesDir recursively; baka mag-exceed sa OS limits ang very deep trees

Nagra-run ng old version ang npx​

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

O kaya i-install globally:

npm install -g i18n-rosetta
i18n-rosetta sync

Performance​

Mabagal ang sync para sa maraming languages​

By default, sequentially tina-translate ng Rosetta ang pairs. Para pabilisin ang multi-language syncs:

  1. Gumamit ng Google Translate para sa high-volume pairs — 10–50× itong mas mabilis kaysa sa LLM translation
  2. Taasan ang batch size (hanggang 50, default ay 30): 
    { "batchSize": 50 }
  3. Gumamit ng mabilis na model — Significantly mas mabilis ang gpt-4o-mini kaysa sa gpt-4o

High API costs​

  • I-check ang batch sizes — Larger batches = fewer API calls = lower cost
  • Gumamit ng prompt caching — Ini-split ng Rosetta ang system/user messages para sa cache hits sa Anthropic at Google models
  • Gumamit ng Google Translate para sa Tier 2 languages — Tingnan ang Translate 30 Languages cookbook

Stuck pa rin?​