Deine erste Übersetzung

Fünf Schritte führen dich vom leeren Projekt zur übersetzten Locale-Datei. Alles, was du brauchst, ist Node.js >=22.14.0 und ein API-Schlüssel für einen Provider, sobald du wirklich übersetzen willst. Die ersten drei Schritte kosten nichts und brauchen kein Konto.

1. Installiere die CLI

verbatra ist eine Dev-Dependency:

npm install --save-dev @verbatra/cli

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

pnpm braucht einen Schritt mehr. pnpm add -D @verbatra/cli installiert korrekt, beendet sich aber mit 1 und ERR_PNPM_IGNORED_BUILDS und hinterlässt eine unbeantwortete pnpm-workspace.yaml, an der jeder spätere pnpm-Befehl im Projekt genauso scheitert. Führe einmal pnpm approve-builds aus und bestätige keinen der beiden Einträge, oder sieh dir in der Fehlerbehebung die nicht-interaktive Lösung an.

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, .verbatra-local/ und verbatra.cache.json, angelegt oder ergänzt, damit ein echter Schlüssel, lokaler Zustand oder der regenerierbare Cache 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. Vorschau ohne API-Schlüssel

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."
  }
}

Sieh dir den Lauf jetzt in der Vorschau an:

verbatra translate --dry-run

Ein Dry-Run baut überhaupt keinen Provider auf, braucht also keinen API-Schlüssel und kann nichts ausgeben. Er liest deine Dateien, vergleicht sie und gibt dieselbe Zusammenfassung pro Locale aus wie ein echter Lauf, ohne einen einzigen String zu senden oder eine einzige Datei zu schreiben. Nutze ihn, um Format, Dateimuster und Locales zu prüfen, bevor du dich irgendwo anmeldest.

verbatra check und verbatra diff kommen genauso ohne Provider aus: check meldet Zählwerte pro Locale, diff listet die genauen Keys.

4. 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. translate, watch und studio laden 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.

5. Übersetze

Mit dem Schlüssel an Ort und Stelle führst du denselben Befehl echt aus:

verbatra translate

verbatra liest die Quell-Locale, sieht, dass jeder Key in de fehlt, sendet sie in Batches an den Provider, lässt jedes Ergebnis durch das Integritäts-Gate laufen 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 vollständig durchkam, und 1, wenn eine fehlschlug oder partial blieb (geschrieben, aber mit weiterhin fehlenden Keys); 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.

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.