Configuration

Gumagana ang Rosetta nang zero-config — nag-a-auto-detect ito ng locale files, format, at target languages mula sa project mo. Para sa mas maraming control, gumawa ng i18n-rosetta.config.json sa project root mo, 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": 30,
  "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 effect ang pag-set ng mga values na ito. :::

Fields

Field	Type	Default	Description
`version`	`number`	`3`	Config schema version. Laging `3`.
`inputLocale`	`string`	`"en"`	Source language code (BCP 47).
`localesDir`	`string`	`"./locales"`	Path papunta sa locale files. Ini-scan ng Rosetta ang directory na ito.
`contentDir`	`string`	`null`	Hugo content directory. Ine-enable nito ang Markdown body translation.
`translatableFields`	`string[]`	`null`	I-override ang default translatable frontmatter fields para sa content translation. Gumagamit ang `null` ng built-in defaults (`title`, `description`, `summary`).
`format`	`string`	`"auto"`	File format: `json`, `toml`, `yaml`, o `auto` (ide-detect mula sa extension).
`model`	`string`	`"google/gemini-3.5-flash"`	Default model para sa LLM methods. Nakadepende ang format sa method: Gumagamit ang OpenRouter ng `provider/model` (hal., `google/gemini-3.5-flash`); gumagamit naman ang direct providers ng bare names (hal., `gpt-4o`, `gemini-2.5-flash`).
`defaultMethod`	`string`	`"llm"`	Default translation method: `llm`, `llm-coached`, `google-translate`, `deepl`, `microsoft-translator`, `libretranslate`, `openai`, `anthropic`, `gemini`, `api`. Mao-override ito ng `--method` CLI flag.
`batchSize`	`number`	`30`	Keys per translation batch. Mas mataas = mas kaunting API calls, pero mas malalaking prompts.
`fallbackPrefix`	`string`	`"[EN] "`	Prefix na idinadagdag sa untranslated fallback values. Ginagamit ng `audit` para ma-detect ang incomplete translations.
`apiKeyEnvVar`	`string`	`"OPENROUTER_API_KEY"`	Environment variable name para sa API key. I-override para sa custom env var names.
`baseUrl`	`string`	`""`	Base URL para sa SEO artifact generation (hreflang, sitemaps, JSON-LD).
`pairs`	`object`	`{}`	Per-pair method, model, at quality overrides. Tingnan ang Pair Configuration.
`languages`	`object`	`{}`	Per-language overrides. Tingnan ang Language Configuration.
`lint.srcDir`	`string`	`null`	Source directory para sa lint scanning. `null` = auto-detect mula sa framework.
`lint.ignore`	`string[]`	`["node_modules", ...]`	Glob patterns na ie-exclude sa lint.
`lint.minLength`	`number`	`2`	Minimum string length para i-flag bilang hardcoded.
`seo.urlPattern`	`string`	`"/:locale/:path"`	URL pattern template para sa hreflang tag generation.
`seo.pages`	`string[]`	`null`	Explicit page list para sa SEO. `null` = auto-detect mula sa locale keys.
`typegen.output`	`string`	`null`	Output path para sa generated TypeScript types. `null` = disabled.
`typegen.autoGenerate`	`boolean`	`false`	Mag-auto-regenerate ng types pagkatapos ng bawat sync.

Pair Configuration

Pwedeng i-configure nang independently ang bawat source→target pair:

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

Field	Type	Description
`method`	`string`	Translation method: `llm`, `llm-coached`, `google-translate`, `deepl`, `microsoft-translator`, `libretranslate`, `openai`, `anthropic`, `gemini`, `api`
`methodPlugin`	`string`	Pangalan ng installed plugin (mula sa `.rosetta/methods/`)
`model`	`string`	I-override ang default model para sa pair na ito
`endpoint`	`string`	Remote API endpoint URL. Required ito kapag ang `method` ay `api`.
`qualityTier`	`string`	Display 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 buong register prompt mula sa card. Kung hindi, gagamitin ang string as-is. Tingnan ang Supported Languages para sa available 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 mong paghaluin ang shorthand at full objects sa iisang block.

Language Fields

Field	Type	Description
`register`	`string`	Style/tone instructions. Pwedeng isang preset key (hal., `casual-tu`, `formal-hapsyo`) o custom text. Tingnan ang Language Cards.
`name`	`string`	Human-readable language name (para sa status display)
`model`	`string`	I-override ang default model
`batchSize`	`number`	I-override ang default batch size
`maxRetries`	`number`	Maximum retry budget para sa failed batches (default: 3)
`script`	`string`	ISO 15924 script code. Tini-trigger nito ang 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 nag-set ang pairs["en:fr"] ng model, ino-override nito ang parehong language-level at global model values. :::

Non-English Source

Kung hindi English ang source language mo:

# 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 translated source values. I-commit ang file na ito para 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 project root mo para i-exclude ang files mula sa lint scanning. Gumagamit ito ng glob patterns, tulad ng .gitignore:

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

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

Export	Ano ang Ginagawa Nito
`TranslationMethod`	Base class para sa lahat ng methods
`LLMMethod`	Base class para sa LLM methods (OpenRouter)
`DirectLLMMethod`	Base class para sa direct LLM providers (OpenAI, Anthropic, Gemini)
`OpenAIMethod`, `AnthropicMethod`, `GeminiMethod`	Direct LLM provider classes
`DeepLMethod`, `MicrosoftTranslatorMethod`, `LibreTranslateMethod`	Traditional MT classes
`GoogleTranslateMethod`	Google Cloud Translation
`LLMCoachedMethod`	Coached LLM (OpenRouter + coaching data)
`APIMethod`	Remote API client
`runSync`, `runContentSync`	Full sync pipeline
`resolveConfig`, `resolvePairs`	Config resolution
`validateTranslations`	Quality gate
`loadCoachingData`, `findDictionaryMatches`	Coaching utilities

Custom Provider Extension

I-extend ang DirectLLMMethod para magdagdag ng bagong LLM provider sa ~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 mo ang translate, coaching, retry loops, model validation, quality tiers, at setup help nang libre. Ang HTTP request shape lang ang provider-specific. Para sa non-LLM adapters na gumagamit ng raw fetch(), gamitin ang shared fetchWithRetry() helper mula sa lib/methods/fetch-with-retry.js imbes na magsulat ng sarili mong retry loop.

Tingnan Din

CLI Reference — lahat ng commands at flags
Translation Methods — pagpili at pag-mix ng methods
Plugin Specification — method plugin manifest format
Architecture — paano nagko-connect ang mga pieces
Supported Languages — built-in language support
How Sync Works — ang translation pipeline

Full Config Reference​

Fields​

Pair Configuration​

Pair Fields​

Language Configuration​

Array of codes (pinakasimple)​

Object na may register strings​

Object na may full config​

Language Fields​

Non-English Source​

Lock File​

.rosettaignore​

Programmatic API​

Available Exports​

Custom Provider Extension​

Tingnan Din​