FAQ

Schnelle Antworten, jede darin verankert, wie verbatra sich tatsächlich verhält. Für symptomorientierte Hilfe bei Fehlermeldungen siehe Fehlerbehebung.

Wie kontrolliere ich die Kosten?

Vier Hebel, alle ohne Provider-Aufruf, bis du dich anders entscheidest:

• Läufe sind standardmäßig inkrementell: Nur Keys, die fehlen oder deren Quelle sich seit der Lock-Baseline geändert hat, gehen an den Provider. Ein unverändertes Projekt kostet beim erneuten Lauf nichts.
• --dry-run (oder translate({ config, dryRun: true })) zeigt exakt, was gesendet würde, ohne Provider-Aufruf und ohne Schreibvorgänge.
• maxTokens in der Konfiguration setzt eine Token-Obergrenze für den ganzen Lauf, und budgetBehavior entscheidet, was bei Erreichen passiert: "warn" (Default) vermerkt es und macht weiter, "stop" hält jeden noch nicht versuchten Key zurück; zurückgehaltene Keys werden beim nächsten Lauf automatisch erneut versucht.
• Gemini hat ein echtes kostenloses API-Kontingent, und der openai-compatible-Provider läuft gegen ein lokales Modell ganz ohne API-Kosten.

Was kostet ein Lauf tatsächlich?

Ein durchgerechnetes Beispiel, um die Größenordnung greifbar zu machen. Ein Projekt mit 400 zu übersetzenden Keys in 3 Locales sendet bei der Standard-maxBatchSize von 50 acht Requests pro Locale, insgesamt also 24. Bei grob 4 Zeichen pro Token, mit 40 Zeichen langen Quellwerten und 20 Zeichen langen Key-Namen sind das etwa 32.400 Eingabe-Tokens und 22.800 Ausgabe-Tokens, also rund 55.000 Tokens für den ganzen Lauf. Auf gemini-2.5-flash ergibt das bei einer illustrativen Rate von $0.10 pro Million Eingabe-Tokens und $0.40 pro Million Ausgabe-Tokens etwa 1,2 Cent.

Die Annahmen hinter dieser Zahl, damit du sie auf dein eigenes Projekt umrechnen kannst: 400 Keys pro Locale und 3 Locales; 40 Zeichen lange Werte und 20 Zeichen lange Key-Namen; kein description, meaning, Glossar oder Tone; maxBatchSize auf dem Standardwert; 4 Zeichen pro Token; Übersetzungen ungefähr so lang wie ihre Quelle. Die Rate ist ein Platzhalter, der die Rechnung konkret macht, kein zitierter Preis: schlage den echten auf der Preisseite deines Providers nach, denn verbatra verfolgt keine Provider-Raten, und sie ändern sich.

Zwei Dinge bestimmen die echte Rechnung stärker als die Key-Anzahl. Jeder Request trägt einen konstanten Overhead von etwa 350 Tokens (die festen Systemregeln und das Ausgabeschema), eine größere maxBatchSize verteilt diese Konstante also auf mehr Keys, und eine kleinere kostet proportional mehr. Und dieser Wert sind nur die Kosten des ersten Laufs: Läufe sind inkrementell, im Alltag zahlst du also für die Handvoll geänderter Strings, nicht für die ganze Datei. DeepL passt gar nicht in diese Formel, weil es Quellzeichen statt Tokens abrechnet.

Siehe Kosten abschätzen für die Methode, den Fall der maschinellen Übersetzung und das Kalibrieren an einem echten gemessenen Lauf.

Mit welchem Provider soll ich anfangen?

Gemini: Es hat ein kostenloses API-Kontingent, du kannst also ein ganzes Projekt kostenlos übersetzen, und ein späterer Wechsel heißt, eine id in der Konfiguration zu ändern. Anthropic und OpenAI sind die Qualitätswahl unter den bezahlten LLMs, DeepL und Google Cloud Translation sind die dedizierten Maschinenübersetzungsoptionen, und openai-compatible behält alles auf deiner eigenen Hardware. Siehe Provider für den vollständigen Vergleich.

Kann ich ein lokales Modell verwenden?

Ja. Der openai-compatible-Provider richtet verbatra über seine baseUrl-Option auf jeden Server, der die OpenAI-Chat-API spricht, etwa LM Studio, Ollama oder vLLM. Die meisten lokalen Server brauchen keinen API-Schlüssel: Wenn weder eine über apiKeyEnvVar benannte Variable noch OPENAI_COMPATIBLE_API_KEY gesetzt ist, sendet verbatra den festen Platzhalter "local". Braucht dein Server doch einen Schlüssel, benenne seine Umgebungsvariable mit apiKeyEnvVar.

Wie behalten Keys ihre Reihenfolge?

Die Adapter der JSON-Familie, von YAML und von ARB tragen Dateien exakt in Dokumentreihenfolge durch den Roundtrip: Bestehende Keys behalten ihre Positionen (auch ganzzahlartige Keys), und neue Keys werden in Quellreihenfolge angehängt. Eine übersetzte Datei ergibt einen sauberen Diff gegenüber ihrer vorherigen Version. Siehe Formate.

Warum wurde eine Übersetzung zum Review markiert?

Akzeptierte Übersetzungen durchlaufen Review-Heuristiken, die verdächtige Ergebnisse markieren, ohne sie zurückzuhalten: eine Länge weit außer Verhältnis zur Quelle (LENGTH_RATIO_OUTLIER), eine Übersetzung identisch zur Quelle (EQUALS_SOURCE), ein verfehlter Glossarbegriff (GLOSSARY_TERM_MISSED), umsortierte Platzhalter (INTEGRITY_REORDERED) oder ein herabgestufter Provider-Pfad (PROVIDER_DEGRADED). Die Flags landen in der needsReview-Liste der Lauf-Zusammenfassung und in Studios Review-Warteschlange. Siehe Übersetzungssicherheit.

Funktioniert verbatra in einem Monorepo?

Ja. Die Konfigurationssuche startet im aktuellen Arbeitsverzeichnis und läuft aufwärts, ein Lauf aus einem Paketverzeichnis findet also die Konfiguration dieses Pakets. Von überall sonst übergib --cwd <dir> (jeder Befehl unterstützt es) oder zeige mit --config <path> auf eine bestimmte Datei. Im SDK heißen dieselben Stellschrauben cwd und configPath auf loadConfig. Das files.pattern und die Lock-Datei werden gegen das Arbeitsverzeichnis aufgelöst.

Was soll ich committen?

Committe deine Locale-Dateien und verbatra.lock.json: Die Lock-Datei hält pro Key den Quell-Content-Hash fest, aus dem jede Übersetzung entstanden ist, und sie zu committen ist es, was Läufe überall inkrementell macht und die Drift-Erkennung funktionieren lässt, auch in CI. Committe nicht .env, .env.local, .verbatra-local/ oder verbatra.cache.json; verbatra init trägt alle vier in .gitignore ein, und translate, watch und import ergänzen einen vorhandenen .gitignore, dem einer davon fehlt. Siehe Die Lock-Datei.

Wie übersetze ich alles neu?

Die Lock-Datei zu löschen tut es nicht: Ohne Baseline zählen Keys, die in Quelle und Ziel existieren, als aktuell, ein Lauf nach dem Löschen der Lock-Datei übersetzt also nichts. Um eine Locale von Grund auf neu aufzubauen, lösche die Datei dieser Locale und führe verbatra translate aus: Jeder Key ist dann fehlend und wird frisch übersetzt. Für einen einzelnen Key nutze Studios Retranslate-Aktion oder das retranslateEntry des SDK. Um Keys neu zu übersetzen, deren Quelltext sich geändert hat, führe einfach translate aus: Das ist der normale inkrementelle Weg.

Heißt die CLI zu benutzen, das SDK zu installieren?

@verbatra/cli hängt von @verbatra/sdk ab, die Installation der CLI bringt das SDK also automatisch mit; es gibt nichts extra zu installieren. Umgekehrt gilt es auch: Das SDK funktioniert eigenständig in deinen eigenen Skripten ohne CLI. Nur @verbatra/studio ist eine separate, optionale Installation, dynamisch geladen vom studio-Befehl.

Wo leben API-Schlüssel?

Nur in Umgebungsvariablen: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY oder GOOGLE_TRANSLATE_API_KEY, plus die Variable, die du für openai-compatible benennst. translate, watch, doctor und studio laden .env und .env.local aus dem Arbeitsverzeichnis (echte Umgebungsvariablen gewinnen). Das Konfigurationsschema lehnt unbekannte Keys genau deshalb ab, damit ein Geheimnis nicht in einer committeten Datei landen kann, und Fehlermeldungen nennen die Variable, aber nie einen Wert. Siehe Provider.

Was prüft verbatra doctor eigentlich?

Fünf Dinge, alle ohne Provider-Aufruf, ohne Netzwerk-Request und ohne einen API-Schlüssel-Wert zu lesen:

• Configuration: Eine Konfigurationsdatei wurde gefunden und besteht die Validierung.
• Format adapter: Das konfigurierte format löst sich zu einem Datei-Adapter auf.
• Provider: Die konfigurierte provider.id löst sich zu einer Provider-Factory auf.
• API key environment variable: Die Variable, aus der dieser Provider seinen Schlüssel liest, ist gesetzt (nur dem Namen nach geprüft, nie am Wert).
• Source locale file: Die Quell-Locale-Datei existiert unter ihrem aufgelösten Pfad, ist eine reguläre Datei und lässt sich im konfigurierten Format parsen.

Jeder Check läuft auch dann, wenn ein früherer fehlgeschlagen ist, ein Lauf meldet also jedes unabhängige Problem auf einmal; die Ausnahme ist die Konfiguration selbst: Schlägt sie beim Laden fehl, werden die vier Checks übersprungen, die sie brauchen.

verbatra doctor

Greife darauf zurück bei einem frischen Checkout, direkt nach verbatra init, oder wann immer ein anderer Befehl fehlgeschlagen ist und du die ganze Liste statt nur des ersten Fehlers willst. Siehe verbatra doctor für die vollständige Check-Tabelle und die Exit-Codes.

Kann ein KI-Agent verbatra für mich einrichten oder bedienen?

Vier verschiedene Oberflächen für vier verschiedene Aufgaben. verbatra mit einem KI-Agenten einrichten ist ein copy-pasteable Prompt für Claude Code, Cursor oder jeden Coding-Agenten, der dein Projekt lesen und Shell-Befehle ausführen kann: Er inspiziert ein bestehendes i18n-Setup, installiert die CLI, erstellt eine passende Konfiguration, führt doctor, check, diff und translate --dry-run aus, um die Arbeit zu zeigen, und stoppt dann, um einen Menschen um Bestätigung zu bitten, bevor er je wirklich einen Provider aufruft. Rezepte für Agenten und Skripte ist die Referenz, um deine eigene Agenten-Schleife auf demselben --json-Envelope und denselben Exit-Codes aufzubauen, die diese Befehle nutzen. Studio mit einem Browser-Agenten bedienen ist noch mal eine andere Oberfläche: ein Opt-in-Flag --expose-agent-tools auf verbatra studio, das WebMCP-Tools registriert, damit ein KI-Agent im Browser ein bereits eingerichtetes Projekt von einem offenen, authentifizierten Dashboard-Tab aus bedienen kann; es ist ausdrücklich nicht für die Ersteinrichtung gedacht. verbatra mcp ist die vierte: ein stdio-MCP-Server für einen terminal-basierten oder headless MCP-Client (Claude Desktop, Claude Code, Cursor), der dieselben Status-, Glossar- und Bearbeitungs-Tools ganz ohne Browser haben will.

Keine der vier gibt einem Agenten die Möglichkeit, ohne einen Menschen im Loop Geld auszugeben. translate selbst hat kein eigenes Ausgaben-Gate, jede agentenfähige Oberfläche legt also einen Bestätigungsschritt oder ein --allow-spend-Flag zwischen den Agenten und einen echten Provider-Aufruf.

Veröffentlicht diese Seite etwas für KI-Agenten und Crawler?

Ja, drei statische Dateien, zur Build-Zeit generiert und immer auf Englisch, egal welche Locale du gerade ansiehst:

• /llms.txt: ein kuratierter Index mit Titel und Beschreibung jeder Doc-Seite, gruppiert wie die Sidebar, als Markdown-Links.
• /llms-full.txt: die komplette Dokumentation in einer Datei, der gerenderte Inhalt jeder Seite der Reihe nach aneinandergehängt, für einen Agenten, der Inhalte direkt einliest, statt Links zu folgen.
• /.well-known/ai.txt: eine Nutzungsrichtlinie, die KI-Crawlern sagt, dass dieses Projekt MIT-lizenziert ist und Crawlen, Indexieren und Zitieren dieser Inhalte willkommen ist.

Alle drei sind aus der Footer-Spalte für KI-Agenten verlinkt.

Ist der Inhalt dieser Seite KI-übersetzt?

Ja, beide Hälften, auf zwei verschiedenen Wegen. Der UI-Rahmen (Navigationsbeschriftungen, Buttons, der Footer, der Landingpage-Text, die Landing-FAQ) lebt in messages/en.json und ihren de-, es- und fr-Geschwistern; die werden mit verbatra selbst maschinell übersetzt, gegen das Format next-intl-json, über den Gemini-Provider, ausgeführt von pnpm i18n, automatisch immer dann, wenn sich die englische Quelle ändert. Das Projekt nutzt hier sein eigenes Tool (Dogfooding). Die Doku-Prosa, die du gerade liest, jeder Guide und jede Referenzseite einschließlich dieser hier, ist locale-suffigiertes MDX (page.mdx, page.de.mdx, page.es.mdx, page.fr.mdx) und ebenfalls KI-übersetzt, nur außerhalb dieser automatisierten Pipeline: pnpm i18n übersetzt nur JSON-, XLIFF-, YAML-, ARB- und Properties-Dateien, nie Markdown, es rührt diese Seiten also nie an. Eine Doku-Seite zu übersetzen ist ein eigener, manueller Schritt, sobald sich die englische Quelle ändert.

Wenn dir im Deutschen, Spanischen oder Französischen etwas seltsam vorkommt, eröffne in beiden Fällen ein Issue: UI-Texte werden an der englischen Quelle korrigiert und von pnpm i18n maschinell neu übersetzt; bei Doku-Prosa bearbeite die MDX-Datei direkt und schick einen Pull Request.