Ga naar hoofdinhoud

Configuratie

Rosetta werkt zero-config — het detecteert automatisch locale-bestanden, het formaat en de doeltalen van uw project. Voor meer controle kunt u i18n-rosetta.config.json aanmaken in de root van uw project, of voer het volgende uit:

npx i18n-rosetta init

Volledige configuratiereferentie​

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 typegen is nog niet geïmplementeerd Het typegen configuratieblok wordt herkend en behouden door de config loader, maar TypeScript type-generatie is nog niet geïmplementeerd. Dit is een tijdelijke aanduiding voor een geplande functie. Het instellen van deze waarden heeft geen effect. :::

Velden​

VeldTypeStandaardBeschrijving
versionnumber3Versie van het configuratieschema. Altijd 3.
inputLocalestring"en"Bron-taalcode (BCP 47).
localesDirstring"./locales"Pad naar locale-bestanden. Rosetta scant deze map.
contentDirstringnullHugo content-map. Schakelt vertaling van Markdown-body in.
translatableFieldsstring[]nullOverschrijf standaard vertaalbare frontmatter-velden voor contentvertaling. null gebruikt ingebouwde standaarden (title, description, summary).
formatstring"auto"Bestandsformaat: json, toml, yaml of auto (detecteren via extensie).
modelstring"google/gemini-3.5-flash"Standaardmodel voor LLM-methoden. Formaat is afhankelijk van de methode: OpenRouter gebruikt provider/model (bijv. google/gemini-3.5-flash); directe providers gebruiken kale namen (bijv. gpt-4o, gemini-2.5-flash).
defaultMethodstring"llm"Standaard vertaalmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Wordt overschreven door de --method CLI-vlag.
batchSizenumber80Sleutels per vertaalbatch. Hoger = minder API-aanroepen, maar grotere prompts.
jsonConcurrencynumber200Maximaal aantal parallelle locale-vertalingen voor JSON-sleutelsynchronisatie. Wordt overschreven door de --json-concurrency CLI-vlag.
contentConcurrencynumber48Maximaal aantal parallelle API-aanroepen voor contentvertaling (Markdown/MDX). Wordt overschreven door de --content-concurrency CLI-vlag.
fallbackPrefixstring"[EN] "Marker-voorvoegsel gebruikt door audit en verify om verouderde onvertaalde waarden van eerdere uitvoeringen te detecteren. Rosetta schrijft dit voorvoegsel niet — het leest het alleen voor detectie.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Naam van de omgevingsvariabele voor de API-sleutel. Overschrijf dit voor aangepaste namen van omgevingsvariabelen.
baseUrlstring""Basis-URL voor het genereren van SEO-artefacten (hreflang, sitemaps, JSON-LD).
pairsobject{}Overschrijvingen per paar voor methode, model en kwaliteit. Zie Paarconfiguratie.
languagesobject{}Overschrijvingen per taal. Zie Taalconfiguratie.
lint.srcDirstringnullBronmap voor lint-scanning. null = automatisch detecteren vanuit het framework.
lint.ignorestring[]["node_modules", ...]Glob-patronen om uit te sluiten van lint.
lint.minLengthnumber2Minimale lengte van de string om als hardcoded te markeren.
seo.urlPatternstring"/:locale/:path"URL-patroonsjabloon voor het genereren van hreflang-tags.
seo.pagesstring[]nullExpliciete paginalijst voor SEO. null = automatisch detecteren vanuit locale-sleutels.
typegen.outputstringnullUitvoerpad voor gegenereerde TypeScript-types. null = uitgeschakeld.
typegen.autoGeneratebooleanfalseAutomatisch types opnieuw genereren na elke synchronisatie.

Paarconfiguratie​

Elk bron→doel-paar kan onafhankelijk worden geconfigureerd:

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

Paarvelden​

VeldTypeBeschrijving
methodstringVertaalmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringNaam van een geïnstalleerde plug-in (uit .rosetta/methods/)
modelstringOverschrijf het standaardmodel voor dit paar
endpointstringExterne API-eindpunt-URL. Vereist wanneer method is ingesteld op api.
qualityTierstringWeergaveniveau (display tier): standard, high, research, verified

Taalconfiguratie​

Talen accepteren drie formaten:

Array van codes (eenvoudigst)​

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

Elke taal krijgt zijn standaardregister uit de ingebouwde registertabel. Talen zonder standaardwaarde krijgen "Professional register.".

Object met registerstrings​

De waarde kan een vooraf ingestelde sleutel (preset key) van de taalkaart zijn, of aangepaste registertekst:

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

Rosetta controleert of de string overeenkomt met een vooraf ingestelde sleutel in de taalkaart. Als dit het geval is, wordt de volledige registerprompt van de kaart gebruikt. Zo niet, dan wordt de string ongewijzigd gebruikt. Zie Ondersteunde talen voor beschikbare voorinstellingen.

Object met volledige configuratie​

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

U kunt verkorte notaties en volledige objecten in hetzelfde blok combineren.

Taalvelden​

VeldTypeBeschrijving
registerstringStijl-/tooninstructies. Kan een vooraf ingestelde sleutel zijn (bijv. casual-tu, formal-hapsyo) of aangepaste tekst. Zie Taalkaarten.
namestringMenselijk leesbare taalnaam (voor statusweergave)
modelstringOverschrijf het standaardmodel
batchSizenumberOverschrijf de standaard batchgrootte
maxRetriesnumberMaximaal budget voor nieuwe pogingen bij mislukte batches (standaard: 3)
scriptstringISO 15924 scriptcode. Activeert scriptvalidatie in de kwaliteitscontrole (quality gate).

:::info Overervingsketen Instellingen worden in deze volgorde opgelost (de eerste wint):

paarniveau → taalniveau → globale configuratie → standaardwaarden

Als pairs["en:fr"] bijvoorbeeld model instelt, overschrijft dit zowel de taal- als de globale model-waarden. :::

Niet-Engelse bron​

Als uw brontaal niet Engels is:

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

Lock-bestand​

Rosetta maakt .i18n-rosetta.lock aan om SHA-256-hashes van vertaalde bronwaarden bij te houden. Commit dit bestand zodat alle ontwikkelaars dezelfde vertaalbasis delen.

Wanneer een bronwaarde verandert, komt de hash niet meer overeen en vertaalt Rosetta die sleutel opnieuw bij de volgende synchronisatie.

.rosettaignore​

Maak .rosettaignore aan in de root van uw project om bestanden uit te sluiten van lint-scanning. Maakt gebruik van glob-patronen, zoals .gitignore:

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

.rosetta/-map​

Rosetta maakt een .rosetta/-map aan in de root van uw project voor de interne status. U dient deze over het algemeen toe te voegen aan .gitignore — het is een lokale optimalisatie, geen projectbron:

.rosetta/
BestandDoelCommitten?
tm.jsonVertaalgeheugencache — slaat eerdere vertalingen op, gekoppeld aan brontekst + locale + methodeNee (lokale cache)
xliff/*.xliffXLIFF-exportbestanden voor beoordeling door professionele vertalersNee (tijdelijk)
methods/Geïnstalleerde methode-plug-in-manifestenJa (gedeelde configuratie)
backups/Pre-wrap back-ups (gemaakt door wrap --undo)Nee (vangnet)

Zie Vertaalgeheugen voor details over tm.json en hoe dit API-kosten bespaart.

Programmatische API​

Voor build-scripts en aangepaste integraties kunt u rechtstreeks vanuit het pakket importeren:

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

Beschikbare exports​

ExportWat het doet
TranslationMethodBasisklasse voor alle methoden
LLMMethodBasisklasse voor LLM-methoden (OpenRouter)
DirectLLMMethodBasisklasse voor directe LLM-providers (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodDirecte LLM-providerklassen
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodTraditionele MT-klassen
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodGecoachte LLM (OpenRouter + coachinggegevens)
APIMethodExterne API-client
runSync, runContentSyncVolledige synchronisatiepijplijn
resolveConfig, resolvePairsConfiguratie-oplossing (config resolution)
validateTranslationsKwaliteitscontrole (quality gate)
loadCoachingData, findDictionaryMatchesCoaching-hulpprogramma's

Aangepaste provider-extensie​

Breid DirectLLMMethod uit om een nieuwe LLM-provider toe te voegen in ~40 regels:

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

U krijgt vertaling, coaching, retry-loops, modelvalidatie, kwaliteitsniveaus en instellingshulp gratis. Alleen de vorm van de HTTP-aanvraag is providerspecifiek. Voor niet-LLM-adapters die ruwe fetch() gebruiken, gebruikt u de gedeelde fetchWithRetry()-helper van lib/methods/fetch-with-retry.js in plaats van uw eigen retry-loop te schrijven.

Zie ook​