Mag-skip sa main content

Configuration

Gumagana ang Rosetta nang zero-config — nag-a-auto-detect ito ng locale files, format, at target languages mula sa project niyo. Para sa mas maraming control, gumawa ng i18n-rosetta.config.json sa inyong project root, o i-run ang:

npx i18n-rosetta init

Full Config Reference​

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 hindi pa implemented ang typegen Ang typegen config block ay nire-recognize at pini-preserve ng config loader, pero hindi pa implemented ang TypeScript type generation. Placeholder po ito para sa isang planned feature. Walang epekto ang pag-set ng mga values na ito. :::

Fields​

FieldTypeDefaultDescription
versionnumber3Config schema version. Laging 3.
inputLocalestring"en"Source language code (BCP 47).
localesDirstring"./locales"Path papunta sa locale files. Ini-scan ng Rosetta ang directory na ito.
contentDirstringnullHugo content directory. Nag-e-enable ng Markdown body translation.
translatableFieldsstring[]nullI-override ang default translatable frontmatter fields para sa content translation. Ang null ay gumagamit ng built-in defaults (title, description, summary).
formatstring"auto"File format: json, toml, yaml, o auto (ide-detect mula sa extension).
modelstring"google/gemini-3.5-flash"Default model para sa LLM methods. Nakadepende ang format sa method: Ang OpenRouter ay gumagamit ng provider/model (hal., google/gemini-3.5-flash); ang direct providers ay gumagamit ng bare names (hal., gpt-4o, gemini-2.5-flash).
defaultMethodstring"llm"Default translation method: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Mao-override ito ng --method CLI flag.
batchSizenumber80Keys per translation batch. Mas mataas = mas kaunting API calls, pero mas malalaking prompts.
jsonConcurrencynumber200Max parallel locale translations para sa JSON key sync. Mao-override ito ng --json-concurrency CLI flag.
contentConcurrencynumber48Max parallel API calls para sa content (Markdown/MDX) translation. Mao-override ito ng --content-concurrency CLI flag.
fallbackPrefixstring"[EN] "Marker prefix na ginagamit ng audit at verify para ma-detect ang legacy untranslated values mula sa mga nakaraang runs. Hindi isinusulat ng Rosetta ang prefix na ito — binabasa lang nito para sa detection.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Environment variable name para sa API key. I-override para sa custom env var names.
baseUrlstring""Base URL para sa SEO artifact generation (hreflang, sitemaps, JSON-LD).
pairsobject{}Per-pair method, model, at quality overrides. Tingnan ang Pair Configuration.
languagesobject{}Per-language overrides. Tingnan ang Language Configuration.
lint.srcDirstringnullSource directory para sa lint scanning. null = auto-detect mula sa framework.
lint.ignorestring[]["node_modules", ...]Glob patterns na i-e-exclude sa lint.
lint.minLengthnumber2Minimum string length para ma-flag bilang hardcoded.
seo.urlPatternstring"/:locale/:path"URL pattern template para sa hreflang tag generation.
seo.pagesstring[]nullExplicit page list para sa SEO. null = auto-detect mula sa locale keys.
typegen.outputstringnullOutput path para sa generated TypeScript types. null = disabled.
typegen.autoGeneratebooleanfalseMag-auto-regenerate ng types pagkatapos ng bawat sync.

Pair Configuration​

Ang bawat source→target pair ay pwedeng i-configure nang independently:

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

Pair Fields​

FieldTypeDescription
methodstringTranslation method: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringPangalan ng isang installed plugin (mula sa .rosetta/methods/)
modelstringI-override ang default model para sa pair na ito
endpointstringRemote API endpoint URL. Required kapag ang method ay api.
qualityTierstringDisplay tier: standard, high, research, verified

Language Configuration​

Tumatanggap ang languages ng tatlong formats:

Array of codes (pinakasimple)​

{
  "languages": ["fr", "de", "ja"]
}

Kinukuha ng bawat language ang default register nito mula sa built-in register table. Ang mga languages na walang default ay makakakuha ng "Professional register.".

Object na may register strings​

Ang value ay pwedeng isang preset key mula sa language card, o custom register text:

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Tinitingnan ng Rosetta kung nagma-match ang string sa isang preset key sa language card. Kung oo, gagamitin ang full register prompt mula sa card. Kung hindi, gagamitin ang string as-is. Tingnan ang Supported Languages para sa mga available na presets.

Object na may full config​

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

Pwede ninyong i-mix ang shorthand at full objects sa iisang block.

Language Fields​

FieldTypeDescription
registerstringStyle/tone instructions. Pwedeng isang preset key (hal., casual-tu, formal-hapsyo) o custom text. Tingnan ang Language Cards.
namestringHuman-readable language name (para sa status display)
modelstringI-override ang default model
batchSizenumberI-override ang default batch size
maxRetriesnumberMaximum retry budget para sa mga failed batches (default: 3)
scriptstringISO 15924 script code. Nagti-trigger ng script validation sa quality gate.

:::info Inheritance chain Nare-resolve ang settings sa ganitong order (first wins):

pair-level → language-level → global config → defaults

Halimbawa, kung ang pairs["en:fr"] ay nag-set ng model, ino-override nito ang parehong language-level at global model values. :::

Non-English Source​

Kung ang source language niyo ay hindi English:

# CLI flag (one-time)
npx i18n-rosetta sync --source fr
i18n-rosetta.config.json (permanent)
{
  "inputLocale": "fr"
}

Lock File​

Gumagawa ang Rosetta ng .i18n-rosetta.lock para i-track ang SHA-256 hashes ng mga translated source values. I-commit ang file na ito para pare-pareho ang translation baseline ng lahat ng developers.

Kapag nagbago ang isang source value, hindi na magmamatch ang hash, at ire-retranslate ng rosetta ang key na iyon sa susunod na sync.

.rosettaignore​

Gumawa ng .rosettaignore sa inyong project root para i-exclude ang mga files sa lint scanning. Gumagamit ito ng glob patterns, tulad ng .gitignore:

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

.rosetta/ Directory​

Gumagawa ang Rosetta ng .rosetta/ directory sa inyong project root para sa internal state. Kadalasan ay dapat niyo itong idagdag sa .gitignore — isa itong local optimization, hindi project source:

.rosetta/
FilePurposeCommit?
tm.jsonTranslation Memory cache — nag-i-store ng mga nakaraang translations na naka-key by source text + locale + methodHindi (local cache)
xliff/*.xliffXLIFF export files para sa professional translator reviewHindi (transient)
methods/Installed method plugin manifestsOo (shared config)
backups/Pre-wrap backups (ginawa ng wrap --undo)Hindi (safety net)

Tingnan ang Translation Memory para sa mga detalye tungkol sa tm.json at kung paano ito nakakatipid sa API costs.

Programmatic API​

Para sa build scripts at custom integrations, mag-import nang direkta mula sa package:

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' }

Available Exports​

ExportAno ang Ginagawa Nito
TranslationMethodBase class para sa lahat ng methods
LLMMethodBase class para sa LLM methods (OpenRouter)
DirectLLMMethodBase class para sa direct LLM providers (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodDirect LLM provider classes
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodTraditional MT classes
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodCoached LLM (OpenRouter + coaching data)
APIMethodRemote API client
runSync, runContentSyncFull sync pipeline
resolveConfig, resolvePairsConfig resolution
validateTranslationsQuality gate
loadCoachingData, findDictionaryMatchesCoaching utilities

Custom Provider Extension​

I-extend ang DirectLLMMethod para magdagdag ng bagong LLM provider sa loob ng ~40 lines:

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.'];
  }
}

Makukuha niyo nang libre ang translate, coaching, retry loops, model validation, quality tiers, at setup help. Ang HTTP request shape lang ang provider-specific. Para sa mga non-LLM adapters na gumagamit ng raw fetch(), gamitin ang shared fetchWithRetry() helper mula sa lib/methods/fetch-with-retry.js sa halip na magsulat ng sarili ninyong retry loop.

See Also​