Konfigurationsdatei

verbatra liest ein kleines, geheimnisfreies Konfigurationsobjekt und validiert es, bevor es irgendetwas tut. Diese Seite ist die vollständige Referenz: jeder Key, wo die Datei liegen kann und wie eine kaputte Konfiguration fehlschlägt.

Eine minimale Konfiguration

import { defineConfig } from "@verbatra/sdk";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"],
  format: "i18next-json",
  files: {
    pattern: "locales/{locale}.json",
  },
  provider: {
    id: "gemini",
    options: {
      model: "gemini-2.5-flash", // example model id; use your provider's current one
      maxOutputTokens: 4096,
    },
  },
});

defineConfig ist ein Identitätshelfer aus @verbatra/sdk. Er gibt sein Argument unverändert zurück und existiert nur, um dir Typinferenz und Autovervollständigung im Editor zu geben.

Jeder Key

Unbekannte Top-Level-Keys werden abgelehnt. Genau deshalb kann auch kein API-Schlüssel in der Konfiguration leben: Schlüssel kommen aus der Umgebung, nicht aus der Datei.

Locales und Dateien

• sourceLocale muss ein nicht-leerer String sein.
• targetLocales muss mindestens eine Locale enthalten, darf sourceLocale nicht einschließen, und keine zwei Einträge dürfen case-insensitiv gleich sein (zum Beispiel wird ["de", "DE"] abgelehnt), da jede Locale beim Export der Name ihres eigenen Excel-Arbeitsblatts wird.
• format ist eines von i18next-json, vue-i18n-json, next-intl-json, ngx-translate-json, xliff, yaml, arb oder properties. Siehe Formate.
• files.pattern muss das {locale}-Token enthalten, das verbatra durch jede Locale ersetzt: locales/{locale}.json wird zu locales/de.json. Pfade werden gegen das Arbeitsverzeichnis aufgelöst.

provider

Ein Objekt, ausgewählt über id: anthropic, openai, gemini, deepl oder openai-compatible. Jeder Provider nimmt seine eigenen options (Modell, Token-Limit und provider-spezifische Felder), und unbekannte Options-Keys werden abgelehnt. Die Optionen pro Provider sind auf Provider dokumentiert.

glossary

Eine Zuordnung von Quellbegriffen zu bevorzugten Zielbegriffen, entweder inline oder als Pfad zu einer JSON-Datei mit derselben Form (ein flaches Objekt aus String-Keys zu String-Werten):

export default defineConfig({
  // ...
  glossary: {
    "Sign in": "Anmelden",
  },
  // or: glossary: "glossary.json",
});

Die beiden Formen schließen einander aus; es gibt keinen Merge zwischen ihnen. Ein relativer Dateipfad wird gegen das Verzeichnis der geladenen Konfigurationsdatei aufgelöst, oder gegen das Arbeitsverzeichnis, wenn die Konfiguration als In-Memory-Override übergeben wird. Die Datei muss UTF-8-kodiert und höchstens 1 MiB groß sein, und sie wird einmal beim Laden der Konfiguration gelesen: verbatra beobachtet sie nicht auf Änderungen, also bearbeite sie und starte neu, damit ein Update greift. Eine fehlende Datei, ungültiges JSON oder ein Wert, der keine flache String-Zuordnung ist, lässt das Laden der Konfiguration mit CONFIG_INVALID fehlschlagen und nennt den aufgelösten Pfad.

Wie das Glossar angewendet wird, hängt vom Provider ab: Die LLM-Provider erhalten die aufgelöste Zuordnung mit der Anfrage und werden angewiesen, ihre Begriffe als bindend zu behandeln, während DeepL eine Begriffszuordnung ignoriert und stattdessen ein per Id konfiguriertes Glossar anwendet. Siehe Provider.

tone

Eines von "formal", "informal" oder "neutral". Die LLM-Provider erhalten den Wert mit der Anfrage und werden angewiesen, ihn einzuhalten; DeepL bildet ihn auf seine Formalitätseinstellung ab. Siehe Provider für die Details pro Provider, einschließlich der Herabstufung im kostenlosen Kontingent von DeepL.

prune

Standardmäßig aus. Wenn true, werden Keys, die in einer Zieldatei stehen, aber in der Quelle fehlen (die verwaisten Keys des Vergleichs), aus der geschriebenen Datei und der Lock-Datei entfernt. Es werden nur verwaiste Keys entfernt, nie andere. Eine prune-Option pro Lauf auf translate (das CLI-Flag --prune) überschreibt den Konfigurationswert.

generatePlurals

Standardmäßig aus. Wenn true, synthetisiert verbatra die CLDR-Pluralformen, die eine Zielsprache verlangt, die Quelle aber nicht liefert (zum Beispiel few und many im Polnischen). Nur für i18next-JSON-Projekte unterstützt, die ein LLM-Provider übersetzt; DeepL, Nicht-i18next-Formate und unbekannte Zielsprachen fallen auf die Plural-Warnung pro Locale zurück. Es gibt kein CLI-Flag, setze das also in der Konfiguration; die translate()-Eingabe des SDK akzeptiert einen generatePlurals-Override pro Lauf, der Vorrang hat.

maxBatchSize

Default 50. Die fehlenden plus geänderten Einträge einer Locale werden in sequenzielle Sub-Batches höchstens dieser Größe aufgeteilt, damit eine überdimensionierte Provider-Anfrage nicht die ganze Locale fehlschlagen lässt. Ein fehlgeschlagener Sub-Batch wird zurückgehalten und beim nächsten Lauf erneut versucht, während die anderen weiter Fortschritt machen. Muss eine positive Ganzzahl sein; null, negative oder gebrochene Werte werden abgelehnt. Nur Konfiguration: Es gibt kein CLI-Flag und keinen Override pro Lauf.

maxTokens und budgetBehavior

maxTokens ist ein Token-Budget für den ganzen Lauf: Eingabe- plus Ausgabe-Tokens, summiert über jeden Provider-Aufruf (Hauptübersetzung wie Pluralgenerierung) und über jede Ziel-Locale. Es wird nach jedem abgeschlossenen Sub-Batch geprüft, nie mittendrin, der Sub-Batch, dessen Abschluss die Obergrenze überschreitet, wurde also schon gesendet, wird normal akzeptiert, und seine Tokens zählen trotzdem: eine nachträgliche weiche Obergrenze, keine harte Vorabprüfung. Nur Konfiguration, kein CLI-Flag.

budgetBehavior entscheidet, was passiert, sobald die Obergrenze erreicht ist:

• "warn" (der Default) vermerkt die Überschreitung und lässt den Lauf genau so weiterlaufen, als wäre kein Budget konfiguriert.
• "stop" hält jeden noch nicht versuchten Key für den Rest des Laufs zurück: die verbleibenden Kandidaten der aktuellen Locale und die Kandidaten jeder späteren Ziel-Locale komplett (deren Vergleich und Verwaisten-Meldung laufen trotzdem; nur der Provider-Aufruf wird übersprungen). Zurückgehaltene Keys behalten ihren vorherigen Lock-Hash und werden beim nächsten Lauf automatisch erneut versucht, genauso wie ein fehlgeschlagener Provider-Aufruf schon heute.

Ein ausgelöstes Budget ändert nie den Exit-Code des Befehls, in keinem der beiden Verhalten. budgetBehavior ohne maxTokens wird akzeptiert und hat keine Wirkung. Gegen einen Provider ohne Token-Zahlen (DeepL, das keinen Verbrauch meldet) meldet sich der Schutzmechanismus als wirkungslos (supported: false im budget der Lauf-Zusammenfassung), statt eine falsche Auslösung zu produzieren.

Suchreihenfolge

verbatra sucht vom Arbeitsverzeichnis aus aufwärts und verwendet die erste Quelle, die es findet. Mehrere vorhandene Quellen sind kein Fehler; der erste Treffer gewinnt. Die Suchreihenfolge ist:

1. package.json (eine "verbatra"-Eigenschaft)
2. .verbatrarc
3. .verbatrarc.json
4. .verbatrarc.yaml
5. .verbatrarc.yml
6. .verbatrarc.js
7. .verbatrarc.cjs
8. .verbatrarc.ts
9. verbatra.config.js
10. verbatra.config.cjs
11. verbatra.config.ts

Um stattdessen genau eine Datei zu laden, übergib --config <path>; ein relativer Pfad wird gegen das Arbeitsverzeichnis aufgelöst. Im SDK hat ein In-Memory-configOverride Vorrang vor einem expliziten configPath, das Vorrang vor der Suche hat. Siehe Programmatische API.

Das Arbeitsverzeichnis und .env

Führe verbatra aus deinem Projektstamm aus, oder lass --cwd darauf zeigen. Das Arbeitsverzeichnis ist der eine Anker für alles, was verbatra auflöst: Die Konfigurationssuche startet dort und läuft aufwärts, .env.local und .env werden von dort geladen, und jeder Locale-Dateipfad wird dagegen aufgelöst. Alle drei am selben Ort zu halten ist es, was ein schlichtes verbatra translate funktionieren lässt.

Die Präzedenz der Umgebung ist, höchste zuerst: eine Variable, die schon in deiner echten Umgebung gesetzt ist, dann .env.local, dann .env. Eine bereits vorhandene Variable wird nie überschrieben.

Wenn das Laden fehlschlägt

Das Laden der Konfiguration schlägt mit einem von zwei strukturierten Fehlercodes fehl:

• CONFIG_NOT_FOUND: Die Suche hat an keinem der Orte oben eine Konfiguration gefunden, oder der explizite --config-Pfad existiert nicht.
• CONFIG_INVALID: Eine Konfiguration wurde gefunden, konnte aber nicht verwendet werden. Das deckt eine Datei ab, die nicht parst, eine Konfiguration, die die Schemavalidierung nicht besteht, und einen Glossar-Dateipfad, der sich nicht auflösen ließ. Die Meldung listet jedes Validierungsproblem mit seinem Key-Pfad, und ein unbekannter Top-Level-Key bekommt den Hinweis, dass API-Schlüssel aus der Umgebung gelesen werden, nicht aus der Konfiguration. Ein roher Parser- oder Dateisystemfehler dringt nie nach außen.

Die CLI meldet beide Fehlschläge und endet mit Exit-Code 2, dem Exit-Code für Boundary-Fehler. Siehe CI und Exit-Codes.