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 DeepL-Fall 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 ist die dedizierte Maschinenübersetzungsoption, 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 oder DEEPL_API_KEY, plus die Variable, die du für openai-compatible benennst. translate, watch 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.