Cookbook: Mag-translate ng 30 Languages

I-scale ang isang project mula sa ilang locales papuntang global coverage. Ang cookbook na ito ay mag-guide sa inyo sa method selection, cost optimization, at CI integration para sa isang totoong multi-language deployment.

Scenario: Mayroon po kayong SaaS app na may en, fr, es. Kailangan ninyong mag-add ng 27 pang languages across three tiers ng quality requirements.

Step 1: I-categorize ang Inyong Languages

Hindi lahat ng 30 languages ay nangangailangan ng parehong approach. I-group po natin sila by available method quality:

Tier	Languages	Method	Bakit
Tier 1 — Premium	`ja`, `ko`, `zh`, `de`, `pt`	`llm` (GPT-4o)	High-value markets, nuanced ang grammar
Tier 2 — Standard	`it`, `nl`, `pl`, `sv`, `da`, `fi`, `no`, `cs`, `ro`, `hu`, `el`, `tr`, `id`, `ms`, `th`, `vi`, `uk`, `bg`	`google-translate`	High-volume, well-supported ng Google
Tier 3 — Coached	`crk`, `oj`, `mi`, `haw`	`llm-coached` + plugins	Low-resource, kailangan ng terminology enforcement

Step 2: Mag-configure Per-Pair

i18n-rosetta.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

Note: Ang mga languages na hindi naka-list sa pairs ay mag-i-inherit ng defaultMethod: "google-translate". Hindi niyo po kailangang i-list lahat ng 30.

impormasyon

Ang crk support ay under development pa — tingnan ang Support a Low-Resource Language para sa status at contribution guidelines.

Step 3: I-set Up ang API Keys

Kakailanganin niyo po ang parehong API keys para sa configuration na ito:

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

Step 4: Mag-Dry Run Muna

Lagi pong mag-preview bago mag-translate ng 30 languages:

npx i18n-rosetta sync --dry

I-review ang output. Ipapakita nito ang:

Kung aling pairs ang gumagamit ng aling method
Ilang keys ang bago/nagbago per locale
Estimated API calls per tier

Step 5: I-run ang Sync

npx i18n-rosetta sync

Ipo-process ng Rosetta ang bawat pair nang independently. Magiging mabilis ang Tier 2 pairs na gumagamit ng Google Translate. Mas mabagal pero higher quality ang Tier 1 LLM pairs. Ang Tier 3 coached pairs naman ay gagamit ng coaching data ng plugin.

Incremental Updates

Pagkatapos ng initial sync, ang mga susunod na runs ay magta-translate lang ng changed o new keys:

# Only keys that changed since last sync
npx i18n-rosetta sync

Tinu-track ng lock file (.i18n-rosetta.lock) kung ano na ang na-translate, kaya hindi niyo na ire-retranslate ang stable content.

Step 6: I-audit ang Quality

I-check ang status ng lahat ng language pairs:

npx i18n-rosetta status

Mag-o-output ito ng table na nagpapakita ng method, model, at quality tier ng bawat pair, at kung available ba ang coaching data o benchmark scores.

Step 7: CI Integration

I-add ito sa inyong GitHub Actions workflow para laging current ang translations sa bawat push:

.github/workflows/i18n-sync.yml
name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx i18n-rosetta sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

Cost Estimation

Para sa isang project na may 500 source keys across 30 languages:

Tier	Languages	Method	Approximate Cost
Tier 1 (5 langs)	ja, ko, zh, de, pt	GPT-4o	~$2.50/full sync
Tier 2 (18 langs)	it, nl, pl, etc.	Google Translate	~$0.90/full sync
Tier 3 (4 langs)	crk, oj, mi, haw	GPT-4o-mini coached	~$0.40/full sync
Total	30 languages	Mixed	~$3.80/full sync

Ang incremental syncs (5–20 changed keys) ay nagkakahalaga lang ng fraction ng isang full sync.

Step 1: I-categorize ang Inyong Languages​

Step 2: Mag-configure Per-Pair​

Step 3: I-set Up ang API Keys​

Step 4: Mag-Dry Run Muna​

Step 5: I-run ang Sync​

Incremental Updates​

Step 6: I-audit ang Quality​

Step 7: CI Integration​

Cost Estimation​

See Also​