Übersetzung · Scribe

Scribe übersetzt den englischen Quelltext mithilfe eines LLMs (Gemini) in jede andere Sprache und speichert die Ergebnisse in SQLite. Sie bearbeiten niemals direkt die Sprachdateien. Stattdessen passen Sie das englische Original an, führen scribe translate erneut aus und committen den Store.

Was übersetzt wird

Pro Dokument werden exakt zwei Dinge an den Übersetzer übergeben:

Frontmatter-Felder, die mit field.translatable() markiert sind, einschließlich solcher in Arrays und Objekten.
Der MDX-Body.

Alles andere (field.structural(), Relationen, integrierte Felder) wird beim Laden aus dem englischen Dokument kopiert. Mit slugStrategy: "localized" generiert der Übersetzer zudem einen spezifischen URL-Slug pro Sprache (ASCII Kebab-Case, bei nicht-lateinischen Schriften transliteriert).

Eine noch nicht übersetzte Sprache führt zur Laufzeit nicht in eine Sackgasse. Über die locale fallback chain liefert resolve() einfach die bestmögliche verfügbare Übersetzung (so fällt pt-BR beispielsweise auf pt und dann auf die Standardsprache zurück). So können Sie neue Sprachen schrittweise einführen.

Staleness-Tracking

Jede gespeicherte Übersetzung erfasst einen SHA-256-Hash der übersetzbaren englischen Inhalte, auf denen sie basiert. Der Befehl scribe translate übersetzt eine Seite nur dann neu, wenn folgende Bedingungen zutreffen:

Für diese Sprache existiert noch keine Übersetzung (missing), oder
Die übersetzbaren englischen Inhalte haben sich in der Zwischenzeit geändert (stale).

Das Bearbeiten eines strukturellen Feldes oder eines Eintrags in der _redirects.json markiert Übersetzungen nicht als veraltet. Diese Felder werden ohnehin nicht übersetzt.

Ausgabevalidierung

Eine Übersetzung wird nur dann dauerhaft gespeichert, wenn sie zwei Prüfungen besteht:

Der zurückgegebene MDX-Body muss sich fehlerfrei parsen lassen (nachdem Escape-Artefakte und Fehler bei den Anführungszeichen in JSX-Attributen, die dem Modell manchmal unterlaufen, bereinigt wurden).
Das zurückgegebene Frontmatter muss erfolgreich gegen Ihr vollständiges Zod-Schema validieren.

Bei Elementen, die bei der Validierung durchfallen, erfolgt am Ende des Durchlaufs automatisch ein erneuter Versuch. Dabei werden die Validierungsfehler an das Modell zurückgemeldet, damit es diese korrigieren kann (Batch-Durchläufe starten hierfür einen zusätzlichen Batch-Job, weiterhin zum günstigeren Batch-Tarif). Alles, was erneut fehlschlägt, taucht in der abschließenden Zusammenfassung mit der entsprechenden Fehlermeldung auf, und der Befehl wird mit einem Fehlercode beendet. Fehlerhafte Modell-Ausgaben gelangen somit niemals in den Store und können folglich auch nicht in der Produktion landen.

Ausführung

export GEMINI_API_KEY=...        # also read from .env / .env.local

scribe status                     # coverage per type and locale
scribe translate                  # interactive picker in a TTY
scribe translate --locale fr de   # specific locales
scribe translate --preset active  # a localePresets group from the config
scribe translate --type blog      # one content type (comma-separated: --type blog,glossary)
scribe translate --slug my-post   # one document
scribe translate --dry-run        # show the worklist + est. tokens/cost, write nothing
scribe translate --force          # re-translate even when hashes match
scribe translate --strategy missing-only   # skip stale, only fill gaps
scribe translate --batch          # force batch mode (the default)
scribe translate --direct         # per-page API calls, immediate results
scribe translate --resume         # pick up pending batch jobs, submit nothing new
scribe translate --concurrency 5  # parallel requests (direct mode only)
scribe translate --model gemini-3.1-pro

Wird scribe translate im Terminal ausgeführt, sehen Sie eine Live-Ansicht des Fortschritts. Diese zeigt den Status der Batch-Jobs, Ergebnisse pro Element, die laufende Anzahl der Tokens und die geschätzten Kosten in US-Dollar. "Thinking Tokens" sind im angezeigten Verbrauch enthalten, sodass die Schätzung genau dem entspricht, was Google später in Rechnung stellt. Verwenden Sie --no-progress (oder führen Sie den Befehl nicht-interaktiv aus, etwa in einer CI-Umgebung), um eine einfache zeilenweise Protokollierung zu erhalten.

Mit --dry-run wird lediglich die Arbeitsliste ausgegeben, ohne dass etwas geschrieben wird. Sie erhalten eine Schätzung der Tokens und der USD-Kosten pro Element sowie in der Gesamtsumme, berechnet aus dem tatsächlichen Prompt und der Größe des englischen Payloads. In Kombination mit --batch wird der Batch-Rabatt direkt in der Schätzung berücksichtigt, sodass Sie eine sehr genaue Vorschau auf die tatsächlichen Kosten des Durchlaufs erhalten.

Anschließend committen Sie einfach die .scribe/store.sqlite.

Batch-Modus und Fortsetzen

Standardmäßig durchläuft die gesamte Arbeitsliste die Gemini Batch API, was im Vergleich zu direkten Aufrufen 50 % der Token-Kosten einspart. Scribe plant alle Anfragen im Voraus (ein Job pro Modell, bei sehr langen Listen aufgeteilt), übermittelt alle Jobs auf einmal und ruft den Status anschließend gesammelt ab. Die Ergebnisse eines Jobs werden sofort gespeichert, sobald dieser abgeschlossen ist. Batch-Jobs sind meist innerhalb von Minuten fertig. Da Google jedoch nur einen Abschluss innerhalb von 24 Stunden garantiert, wartet der Befehl ab, anstatt die Ergebnisse Seite für Seite zu streamen.

Jeder Job wird im SQLite-Store vermerkt, bevor der Abruf beginnt. Dabei wird auch ein Snapshot der englischen Quelle gespeichert, aus der das jeweilige Element übermittelt wurde. Dadurch können Durchläufe problemlos unterbrochen werden:

Wenn Sie während des Abrufs abbrechen (Strg+C), geht nichts verloren.
Der Befehl scribe translate --resume prüft ausstehende Jobs, verarbeitet die bereits abgeschlossenen und übermittelt keine neuen Anfragen.
Ein normaler Start von scribe translate greift ebenfalls zuerst ausstehende Jobs auf. Bereits laufende Elemente werden so niemals doppelt übermittelt.
Es ist völlig unproblematisch, eine englische Seite zu bearbeiten, während ihr Batch-Job noch läuft. Das Ergebnis wird dem Snapshot zugeordnet, auf dessen Basis die Übersetzung gestartet wurde, und beim nächsten Durchlauf automatisch als veraltet erkannt.

Bevorzugen Sie sofortige, seitenweise Ergebnisse zum vollen Preis? Dann nutzen Sie --direct. Damit werden API-Aufrufe pro Seite inklusive paralleler Verarbeitung über --concurrency wiederhergestellt. Im Terminal bietet die interaktive Auswahl dieselbe Möglichkeit. Vorübergehende API-Fehler (429, 5xx, Verbindungsabbrüche) werden in beiden Modi automatisch mit exponentiellem Backoff wiederholt.

Den Übersetzer steuern

Der integrierte Prompt zielt auf Transkreation ab, nicht auf wörtliche Übersetzung. Das Modell agiert wie ein muttersprachlicher Texter, der die lokalisierte Ausgabe verfasst. Es adaptiert Redewendungen und Wortspiele passend zur Zielsprache, anstatt sie Wort für Wort zu übertragen, und wendet dabei die landestypischen typografischen Konventionen an (Anführungszeichen, Apostrophe, Abstände bei Satzzeichen). Ihre Einstellungen für context, rules und prompt bauen genau auf diesem Fundament auf.

Projektweite Standards und typspezifische Überschreibungen:

export default defineConfig({
  translate: {
    context: "MyBrand is a B2B SaaS. Never translate the brand name MyBrand.",
    rules: ["Keep numbers and statistics accurate."],
  },
  types: [
    defineContentType({
      id: "blog",
      // ...
      translate: {
        rules: [
          "Preserve all MDX/JSX component tags, props, and URLs exactly.",
          "Translate link anchor text; never change href paths.",
        ],
      },
    }),
  ],
});

Option	Gültigkeit	Beschreibung
`context`	Projekt + Typ	Marken- und Fachkontext, der jeder Anfrage vorangestellt wird (Kontexte aus Projekt und Typ werden kombiniert).
`rules`	Projekt + Typ	Zusätzliche Regeln, die an die Standardwerte angehängt werden.
`prompt`	Projekt oder Typ	Weitere Lokalisierungsanweisungen, die vor der Sprachdirektive eingefügt werden (Name und Code der Zielsprache werden immer angehängt).
`defaultModel` / `model`	Projekt / Typ	ID des Gemini-Modells. Standard: `gemini-3.1-pro` (kann auch über die Umgebungsvariable `PROSE_GEMINI_MODEL` oder mit `--model` überschrieben werden).

Zu den integrierten Regeln, die immer angewendet werden, gehören folgende Anweisungen: Markennamen sollen nicht übersetzt werden, es sei denn, es gibt einen bekannten lokalen Namen im Zielmarkt. MDX-Bodies müssen mit echten Zeilenumbrüchen zurückgegeben werden (kein maskiertes \n). Die Anführungszeichen von JSX-Attributen sind zu korrigieren, falls Werte doppelte Anführungszeichen enthalten.

Übersetzungen überprüfen

scribe history blog my-post fr    # EN snapshot timeline for one page
scribe studio                     # read-only web UI on :3600

Jede Übersetzung ist mit einem Snapshot der englischen Quelle verknüpft, aus der sie erstellt wurde (dieser wird in derselben SQLite-Datei gespeichert). So können Sie genau nachvollziehen, wann, auf welcher Basis und mit welchem Modell eine Seite übersetzt wurde. Der Befehl scribe history gibt diesen zeitlichen Verlauf aus. Im Studio sehen Sie zudem die Abdeckung pro Sprache, die aktuelle Arbeitsliste der fehlenden oder veralteten Einträge sowie Details auf Dokumentebene, bei denen der Snapshot direkt neben der gespeicherten Übersetzung angezeigt wird.

Sprach-Presets

Für schrittweise Rollouts können Sie Sprachgruppen in der Konfiguration benennen und diese gezielt über --preset ansteuern:

localePresets: {
  active: ["fr", "es", "ja"],
  ultraLight: ["fr"],
}

scribe translate --preset ultraLight