Deine erste Übersetzung

Vier Schritte führen dich vom leeren Projekt zur übersetzten Locale-Datei. Alles, was du brauchst, sind Node.js >=22.14.0 und ein API-Schlüssel für einen Provider.

1. Installiere die CLI

verbatra ist eine Dev-Dependency:

pnpm add -D @verbatra/cli

npm und yarn funktionieren auch. Das Paket liefert das verbatra-Binary; führe es über deinen Paketmanager aus (pnpm verbatra ..., npx verbatra ... oder yarn verbatra ...). Die Codeblöcke unten verwenden den bloßen Namen.

2. Erzeuge eine Konfiguration

verbatra init --provider gemini

Mit angeschlossenem Terminal fragt init alles ab, was du nicht als Flag übergeben hast, jeweils mit einem Default:

• den Provider: einer von anthropic, openai, gemini oder deepl (Flag --provider, die einzige Eingabe ohne Default)
• die Quell-Locale, Default en (--source)
• die Ziel-Locales, kommagetrennt, Default de (--targets)
• das Muster der Locale-Dateien, Default locales/{locale}.json (--path)

Übergib --yes, um die Abfragen zu überspringen und die Defaults zu nehmen. Ohne Terminal (zum Beispiel in CI) fragt init nie nach; es verwendet die Defaults und verlangt nur --provider.

init schreibt drei Dinge:

• verbatra.config.ts: deine Projektkonfiguration, vor dem Schreiben gegen das echte Schema validiert
• .env.example: nennt die Schlüsselvariable des Providers, nie einen Schlüsselwert
• .gitignore-Einträge für .env, .env.local und .verbatra-local/, angelegt oder ergänzt, damit ein echter Schlüssel oder lokaler Zustand nie in einem Commit landet

Ein erneutes init überspringt Dateien, die schon existieren; --force überschreibt sie. Es füllt außerdem format anhand deiner Dependencies vor: Ein Projekt mit i18next, vue-i18n, next-intl oder @ngx-translate/core bekommt das passende JSON-Format, alles andere fällt auf i18next-json mit einem TODO-Kommentar zum Ändern zurück. Für Gemini sieht das Gerüst so aus:

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

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

3. Setze deinen API-Schlüssel

Schlüssel kommen aus der Umgebung, nie aus der Konfigurationsdatei. Jeder gehostete Provider liest genau eine Variable; für Gemini ist das GEMINI_API_KEY. Kopiere das erzeugte Beispiel und trage deinen Schlüssel ein:

cp .env.example .env

Öffne dann .env und füge deinen Schlüssel nach GEMINI_API_KEY= ein. verbatra lädt vor einem Lauf .env.local und dann .env aus dem Arbeitsverzeichnis, und eine Variable, die schon in deiner Shell gesetzt ist, gewinnt immer. Siehe Provider für die Variable jedes Providers.

4. Übersetze

Wenn du noch keine Quelldatei hast, lege eine unter dem konfigurierten Muster an, zum Beispiel locales/en.json:

{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

Dann führe aus:

verbatra translate

verbatra liest die Quell-Locale, sieht, dass jeder Key in de fehlt, sendet sie in Batches an den Provider, prüft jedes Ergebnis auf Platzhalter- und ICU-Integrität und schreibt locales/de.json. Der Lauf endet mit einer Zusammenfassung pro Locale: übersetzte Keys, unveränderte Keys, verwaiste Keys und etwaige Hinweise. Der Exit-Code ist 0, wenn jede Locale erfolgreich war, und 1, wenn eine fehlgeschlagen ist; ergänze --json für eine maschinenlesbare Zusammenfassung.

Was gerade passiert ist

Drei Dinge liegen jetzt auf der Platte:

• locales/de.json: die Ziel-Locale-Datei. Die Datei hat dieselben Keys wie deine Quelle, in derselben Dokumentreihenfolge, und {{name}} hat die Übersetzung intakt überstanden; ein Ergebnis, das den Platzhalter verworfen hätte, wäre zurückgehalten und nicht geschrieben worden.

• verbatra.lock.json: die Lock-Datei. Für jede Ziel-Locale bildet sie jeden übersetzten Key auf einen Hash des Quellstrings ab, aus dem die Übersetzung entstanden ist:

  {
    "version": 1,
    "locales": {
      "de": {
        "cart.empty": "<source content hash>",
        "greeting": "<source content hash>"
      }
    }
  }

• .verbatra-local/: prozesslokaler Zustand (der Run-Status-Schnappschuss und die Schreibsperren pro Locale). init hat das Verzeichnis in .gitignore eingetragen; committe es nie.

Die Lock-Datei ist die Baseline für jeden künftigen Lauf. Führe verbatra translate erneut aus, ohne etwas zu bearbeiten, und nichts wird gesendet: Jeder Key ist bereits aktuell. Ändere einen einzigen Quellstring, und nur dieser Key wird neu übersetzt. Um einen Lauf ohne Provider-Aufruf und ohne einen einzigen Schreibvorgang in der Vorschau zu sehen, verwende verbatra translate --dry-run.

Nächste Schritte

• Eine Sprache hinzufügen: nimm eine neue Ziel-Locale in dieses Setup auf.
• Wie es funktioniert: die komplette Pipeline hinter einem Lauf.
• Konfigurationsdatei: alles, was verbatra.config.ts enthalten kann.