Halte jede Locale-Datei im Gleichschritt mit deiner Quelle.
verbatra übersetzt deine i18n-Locale-Dateien inkrementell: Es sendet nur die neuen und geänderten Strings an den Provider, den du konfigurierst, prüft jedes Ergebnis und schreibt die Dateien direkt zurück.
pnpm add -D @verbatra/cliAn example verbatra command-line session.
- verbatra init
- ✓ created verbatra.config.ts
- source en · targets de, es, fr
- provider gemini · key from GEMINI_API_KEY
- verbatra translate
- diff en.json · 12 new · 0 changed · 108 unchanged
- de 12 translated · 108 unchanged · 0 withheld
- es 12 translated · 108 unchanged · 0 withheld
- fr 12 translated · 108 unchanged · 0 withheld
- ✓ 36 keys translated in 5.4s · 0 skipped · lock updated
- verbatra diff
- en.json · 120 keys · source of truth
- de 2 new · 1 changed · 117 up to date
- es 0 new · 0 changed · 120 up to date
- fr 5 new · 0 changed · 115 up to date
- 8 keys would be sent · run verbatra translate to apply
- verbatra watch
- watching en.json for changes
- en.json changed · 1 new key
- de 1 translated · 0 withheld
- ✓ 3 keys translated · waiting for changes
Das Problem
Du pflegst eine Quell-Locale von Hand. Jede andere Locale-Datei driftet ab, während diese Quelle sich weiterentwickelt: Neue Keys fehlen in den Zielen, bearbeitete Quellstrings hinterlassen veraltete Übersetzungen, und gelöschte Keys bleiben als Waisen zurück. Von Hand aufzuholen skaliert nicht, und bei jeder Änderung alles neu zu übersetzen ist langsam, kostet Provider-Tokens für Strings, die schon in Ordnung waren, und wirbelt Texte durcheinander, die dein Team bereits geprüft hat.
Wie verbatra es löst
Eine committete Lock-Datei, verbatra.lock.json, hält für jeden übersetzten Key den Hash des Quellstrings fest, aus dem seine Übersetzung entstanden ist. Jeder Lauf liest die Quell-Locale, vergleicht jedes Ziel mit ihr und mit dieser Baseline und sendet nur die fehlenden und geänderten Keys an den Provider. Keys, die noch aktuell sind, bleiben unangetastet: Führe translate zweimal hintereinander aus, und der zweite Lauf macht überhaupt keinen Provider-Aufruf.
Jeder String, den der Provider zurückgibt, wird vor dem Schreiben geprüft: Platzhalter-Integrität und ICU-Integrität werden erzwungen, und eine Übersetzung, die eine von beiden verletzt, wird zurückgehalten statt ausgeliefert und beim nächsten Lauf erneut versucht. Die schreibgeschützten Befehle check und diff melden Drift, ohne etwas zu schreiben, sodass deine CI anhand ihrer Exit-Codes ein Gate setzen kann.
verbatra liest und schreibt acht Formate (i18next-, vue-i18n-, next-intl- und ngx-translate-JSON, XLIFF, YAML, Flutter ARB und Java/Spring-Properties) und übersetzt über fünf Provider (Anthropic, OpenAI, Gemini, DeepL und jeden OpenAI-kompatiblen Server, auch lokale) hinter einer einzigen Schnittstelle. Siehe Formate und Provider.
Die Pakete
verbatra erscheint als drei npm-Pakete:
- @verbatra/cli liefert das
verbatra-Binary mit acht Befehlen:init,translate,watch,check,diff,export,importundstudio. Es ist ein dünner Wrapper über dem SDK, alles, was es tut, ist also auch programmatisch verfügbar. Starte hier. - @verbatra/sdk ist der Motor darunter: einmaliges
translate(), langlaufendeswatch(), schreibgeschütztecheck()unddiff(), der Excel-Arbeitsmappen-Roundtrip für menschliche Übersetzer und das Laden der Konfiguration. Nutze es direkt aus Skripten, Build-Tools oder CI. Siehe das SDK. - @verbatra/studio ist Verbatra Studio, ein lokales Dashboard über deinem Projekt mit eingebautem Bearbeiten und einer Review-Warteschlange. Die CLI startet es mit
verbatra studio; kostenpflichtige Provider-Aufrufe aus Studio bleiben aus, solange du nicht--allow-spendübergibst. Siehe Review in Studio.