Zum Hauptinhalt springen

Konfiguration

Rosetta funktioniert konfigurationsfrei — es erkennt Lokalisierungsdateien, das Format und die Zielsprachen automatisch in Ihrem Projekt. Für mehr Kontrolle erstellen Sie i18n-rosetta.config.json im Stammverzeichnis Ihres Projekts oder führen Sie Folgendes aus:

npx i18n-rosetta init

Vollständige Konfigurationsreferenz​

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 ist noch nicht implementiert Der Konfigurationsblock typegen wird vom Konfigurationslader erkannt und beibehalten, aber die Generierung von TypeScript-Typen ist noch nicht implementiert. Dies ist ein Platzhalter für eine geplante Funktion. Das Festlegen dieser Werte hat keine Auswirkungen. :::

Felder​

FeldTypStandardwertBeschreibung
versionnumber3Version des Konfigurationsschemas. Immer 3.
inputLocalestring"en"Sprachcode der Ausgangssprache (BCP 47).
localesDirstring"./locales"Pfad zu den Lokalisierungsdateien. Rosetta durchsucht dieses Verzeichnis.
contentDirstringnullHugo-Inhaltsverzeichnis. Aktiviert die Übersetzung des Markdown-Textkörpers.
translatableFieldsstring[]nullÜberschreibt die standardmäßigen übersetzbaren Frontmatter-Felder für die Inhaltsübersetzung. null verwendet integrierte Standardwerte (title, description, summary).
formatstring"auto"Dateiformat: json, toml, yaml oder auto (Erkennung anhand der Dateiendung).
modelstring"google/gemini-3.5-flash"Standardmodell für LLM-Methoden. Das Format hängt von der Methode ab: OpenRouter verwendet provider/model (z. B. google/gemini-3.5-flash); direkte Anbieter verwenden reine Namen (z. B. gpt-4o, gemini-2.5-flash).
defaultMethodstring"llm"Standard-Übersetzungsmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Wird durch das CLI-Flag --method überschrieben.
batchSizenumber80Schlüssel pro Übersetzungsstapel (Batch). Höher = weniger API-Aufrufe, aber größere Prompts.
jsonConcurrencynumber200Maximale parallele Lokalisierungsübersetzungen für die JSON-Schlüsselsynchronisation. Wird durch das CLI-Flag --json-concurrency überschrieben.
contentConcurrencynumber48Maximale parallele API-Aufrufe für die Inhaltsübersetzung (Markdown/MDX). Wird durch das CLI-Flag --content-concurrency überschrieben.
fallbackPrefixstring"[EN] "Markierungspräfix, das von audit und verify verwendet wird, um veraltete unübersetzte Werte aus früheren Durchläufen zu erkennen. Rosetta schreibt dieses Präfix nicht — es liest es nur zur Erkennung.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Name der Umgebungsvariable für den API-Schlüssel. Überschreiben Sie dies für benutzerdefinierte Namen von Umgebungsvariablen.
baseUrlstring""Basis-URL für die Generierung von SEO-Artefakten (hreflang, Sitemaps, JSON-LD).
pairsobject{}Überschreibungen von Methode, Modell und Qualität pro Sprachpaar. Siehe Paar-Konfiguration.
languagesobject{}Überschreibungen pro Sprache. Siehe Sprachkonfiguration.
lint.srcDirstringnullQuellverzeichnis für den Lint-Scan. null = automatische Erkennung anhand des Frameworks.
lint.ignorestring[]["node_modules", ...]Glob-Muster, die vom Linting ausgeschlossen werden sollen.
lint.minLengthnumber2Minimale Zeichenfolgenlänge, um als fest codiert (hardcoded) markiert zu werden.
seo.urlPatternstring"/:locale/:path"URL-Mustervorlage für die Generierung von hreflang-Tags.
seo.pagesstring[]nullExplizite Seitenliste für SEO. null = automatische Erkennung aus Lokalisierungsschlüsseln.
typegen.outputstringnullAusgabepfad für generierte TypeScript-Typen. null = deaktiviert.
typegen.autoGeneratebooleanfalseTypen nach jeder Synchronisation automatisch neu generieren.

Paar-Konfiguration​

Jedes Ausgangs-→Zielsprachen-Paar kann unabhängig konfiguriert werden:

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

Paar-Felder​

FeldTypBeschreibung
methodstringÜbersetzungsmethode: llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringName eines installierten Plugins (aus .rosetta/methods/)
modelstringÜberschreibt das Standardmodell für dieses Paar
endpointstringRemote-API-Endpunkt-URL. Erforderlich, wenn method auf api gesetzt ist.
qualityTierstringAnzeige-Ebene (Tier): standard, high, research, verified

Sprachkonfiguration​

Sprachen akzeptieren drei Formate:

Array von Codes (am einfachsten)​

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

Jede Sprache erhält ihr Standardregister aus der integrierten Registertabelle. Sprachen ohne Standardwert erhalten "Professional register.".

Objekt mit Register-Zeichenfolgen​

Der Wert kann ein Voreinstellungsschlüssel (Preset-Key) aus der Sprachkarte oder ein benutzerdefinierter Registertext sein:

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

Rosetta prüft, ob die Zeichenfolge mit einem Voreinstellungsschlüssel in der Sprachkarte übereinstimmt. Wenn dies der Fall ist, wird der vollständige Register-Prompt aus der Karte verwendet. Wenn nicht, wird die Zeichenfolge unverändert verwendet. Siehe Unterstützte Sprachen für verfügbare Voreinstellungen.

Objekt mit vollständiger Konfiguration​

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

Sie können Kurzschreibweisen und vollständige Objekte im selben Block mischen.

Sprachfelder​

FeldTypBeschreibung
registerstringAnweisungen zu Stil/Tonfall. Kann ein Voreinstellungsschlüssel (z. B. casual-tu, formal-hapsyo) oder benutzerdefinierter Text sein. Siehe Sprachkarten.
namestringMenschenlesbarer Sprachname (für die Statusanzeige)
modelstringÜberschreibt das Standardmodell
batchSizenumberÜberschreibt die Standard-Stapelgröße (Batch-Größe)
maxRetriesnumberMaximales Wiederholungsbudget für fehlgeschlagene Stapel (Standard: 3)
scriptstringISO 15924-Skriptcode. Löst die Skriptvalidierung im Quality Gate aus.

:::info Vererbungskette Einstellungen werden in dieser Reihenfolge aufgelöst (die erste gewinnt):

Paar-Ebene → Sprach-Ebene → Globale Konfiguration → Standardwerte

Wenn beispielsweise pairs["en:fr"] den Wert model festlegt, überschreibt dies sowohl die sprachbezogenen als auch die globalen model-Werte. :::

Nicht-englische Ausgangssprache​

Wenn Ihre Ausgangssprache nicht Englisch ist:

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

Lock-Datei​

Rosetta erstellt .i18n-rosetta.lock, um SHA-256-Hashes der übersetzten Ausgangswerte zu verfolgen. Committen Sie diese Datei, damit alle Entwickler dieselbe Übersetzungsbasis teilen.

Wenn sich ein Ausgangswert ändert, stimmt der Hash nicht mehr überein, und Rosetta übersetzt diesen Schlüssel bei der nächsten Synchronisation neu.

.rosettaignore​

Erstellen Sie .rosettaignore im Stammverzeichnis Ihres Projekts, um Dateien vom lint-Scan auszuschließen. Verwendet Glob-Muster, wie .gitignore:

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

.rosetta/-Verzeichnis​

Rosetta erstellt ein .rosetta/-Verzeichnis im Stammverzeichnis Ihres Projekts für den internen Status. Sie sollten dieses im Allgemeinen zu .gitignore hinzufügen — es handelt sich um eine lokale Optimierung, nicht um Projektquellcode:

.rosetta/
DateiZweckCommitten?
tm.jsonTranslation-Memory-Cache — speichert vorherige Übersetzungen, verschlüsselt nach Ausgangstext + Gebietsschema (Locale) + MethodeNein (lokaler Cache)
xliff/*.xliffXLIFF-Exportdateien für die Überprüfung durch professionelle ÜbersetzerNein (temporär)
methods/Manifeste der installierten Methoden-PluginsJa (gemeinsame Konfiguration)
backups/Pre-Wrap-Backups (erstellt durch wrap --undo)Nein (Sicherheitsnetz)

Siehe Translation Memory für Details zu tm.json und wie es API-Kosten spart.

Programmatische API​

Für Build-Skripte und benutzerdefinierte Integrationen importieren Sie direkt aus dem Paket:

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

Verfügbare Exporte​

ExportFunktion
TranslationMethodBasisklasse für alle Methoden
LLMMethodBasisklasse für LLM-Methoden (OpenRouter)
DirectLLMMethodBasisklasse für direkte LLM-Anbieter (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodKlassen für direkte LLM-Anbieter
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodKlassen für traditionelle maschinelle Übersetzung (MT)
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodGecoachtes LLM (OpenRouter + Coaching-Daten)
APIMethodRemote-API-Client
runSync, runContentSyncVollständige Synchronisations-Pipeline
resolveConfig, resolvePairsKonfigurationsauflösung
validateTranslationsQuality Gate
loadCoachingData, findDictionaryMatchesCoaching-Dienstprogramme

Benutzerdefinierte Anbieter-Erweiterung​

Erweitern Sie DirectLLMMethod, um einen neuen LLM-Anbieter in ca. 40 Zeilen hinzuzufügen:

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

Sie erhalten Übersetzung, Coaching, Wiederholungsschleifen (Retry Loops), Modellvalidierung, Qualitätsstufen (Quality Tiers) und Einrichtungshilfe kostenlos dazu. Nur die Form der HTTP-Anfrage ist anbieterspezifisch. Für Nicht-LLM-Adapter, die reines fetch() verwenden, nutzen Sie den gemeinsamen fetchWithRetry()-Helfer aus lib/methods/fetch-with-retry.js, anstatt Ihre eigene Wiederholungsschleife zu schreiben.

Siehe auch​