Docs / Erste Schritte
Maschinell übersetzte Seite
verbatra mit einem KI-Agenten einrichten
Ein kurzer Prompt, mit dem ein KI-Coding-Agent verbatra in ein Projekt mit bestehendem i18n-Setup einbaut, mit Bestätigung durch dich, bevor etwas Geld kostet.
Diese Seite ist für ein Projekt gedacht, das bereits committete Locale-Dateien hat. Füge den Prompt für KI-Agenten von oben in Claude Code, Codex, Gemini CLI, Cursor oder jeden Agenten ein, der Shell-Befehle ausführt. Er folgt den Schritten unten und fragt dich drei Dinge:
- Welchen Provider er nutzen soll, außer das Projekt macht es klar.
- Den API-Key: Der Agent lässt seine Variable in
.envleer, damit du sie ausfüllst, und fragt nie nach dem Key. - Das Go vor dem ersten echten
translate, das sofort Geld kostet.
Die Schritte, denen der Agent folgt
Agent: Folge diesen Schritten der Reihe nach und überspring nie den Halt in Schritt 6.
1. Das bestehende Setup prüfen
Bevor du etwas änderst, finde die i18n-Bibliothek in der package.json (etwa i18next, vue-i18n oder next-intl) und die Locale-Dateien. Notiere die Quell-Locale, jede bereits vorhandene Ziel-Locale und das Pfadmuster mit einem {locale}-Token, etwa locales/{locale}.json. Wähle deinen Stack ordnet jedem Stack seine Format-ID und sein Layout zu, Formate sagt, welche Dateien schon existieren müssen. Reines JSON ohne i18n-Bibliothek: Platzhalter {{name}} bedeuten i18next-json, einfache Klammern {name} bedeuten vue-i18n-json.
2. Die CLI installieren
npm install --save-dev @verbatra/clipnpm, yarn und bun funktionieren auch. Bestätige keine Install-Skripte, weder in pnpm approve-builds noch in allowScripts von npm: verbatra braucht keines davon.
3. Konfiguration und Agenten-Dateien anlegen
npx @verbatra/cli init --provider <provider> --yes --json --agentFrag den Menschen, welcher Provider genutzt werden soll, außer das Projekt macht es klar. Wähl nie einen, der bei einem Dienst Kosten verursacht, dem der Mensch nicht zugestimmt hat, und übergib init nie einen API-Key-Wert. Provider listet die IDs; none schaltet die maschinelle Übersetzung ab. init erkennt Format, Pfadmuster und Locales, gibt einen JSON-Envelope aus und fragt nie nach. --agent schreibt außerdem einen verbatra-Abschnitt in AGENTS.md (oder in CLAUDE.md, wenn das die einzige Anweisungsdatei ist oder schon den verbatra-Abschnitt enthält) und den verbatra-MCP-Server mit ausgeschalteten Ausgaben in die Konfiguration jedes erkannten Clients, die .mcp.json von Claude Code, wenn er Claude Code oder gar keinen Client findet; result.agent.clients listet die Dateien.
| Exit-Code und Fehlercode | Tu das |
|---|---|
0 | Vergleiche result.config mit Schritt 1, beginnend mit jedem Eintrag in result.sources, der default sagt; result.config.files.localeStyle erscheint nur, wenn die Dateien Locales nicht wie geschrieben benennen. Stimmt etwas nicht, führ den Befehl erneut mit dem richtigen --format, --path, --source oder --targets plus --force aus. |
2, FORMAT_ oder LAYOUT_ | Wähl aus candidates und führ den Befehl erneut mit --format oder --path aus. Nebeneinanderliegende Namespace-Dateien: Halt an und frag den Menschen, denn eine Konfiguration deckt ein Dateimuster ab. |
2, MISSING_ | Die Meldung nennt jedes noch fehlende Flag. |
2, CONFIG_ | Sag dem Menschen, welchen Provider die vorhandene Konfiguration nutzt, und warte auf seine Bestätigung. Führ dann npx @verbatra/cli init --agent --json aus, das die Konfiguration behält und nur die Agenten-Dateien ergänzt. Frag, bevor du --force übergibst. |
init beschreibt jedes Flag.
4. Den API-Key dem Menschen überlassen
Überspring diesen Schritt beim Provider none. Die Key-Variable steht in result.apiKeyEnvVar; nach CONFIG_ ist sie null, dann nimmst du den Namen aus der fehlschlagenden Prüfung api-key von npx @verbatra/cli doctor --json. Kopier .env.example nach .env oder leg .env an, wenn init kein Beispiel geschrieben hat, nenn dort die Variable mit leerem Wert und sag dem Menschen, dass er sie ausfüllen soll. Schreib, erfinde oder erfrage nie einen API-Key-Wert. Mach weiter, ohne zu warten.
5. Das Setup ohne Kosten prüfen
npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --jsonKeiner dieser Befehle ruft einen Provider auf, braucht einen API-Key oder schreibt eine Datei. Behebe jede fehlschlagende doctor-Prüfung, die du in verbatra.config.ts beheben kannst; die Prüfung api-key besteht erst, wenn der Mensch den API-Key gesetzt hat, also dreh dich nicht in einer Schleife darum. Bei check oder diff ist Exit 1 (nicht synchron) vor einem ersten Lauf zu erwarten; nur Exit 2 ist ein Setup-Problem. Beim Provider none endet translate --dry-run mit 3, wenn Keys für einen menschlichen Übersetzer übrig bleiben. Übersetzt werden nur Keys, die im Ziel fehlen, und ein leerer String zählt als vorhanden, also frag, bevor du Platzhalter-Keys mit "" löschst.
6. Anhalten und fragen
Fass zusammen, wie viele Keys pro Locale ausstehen und was translate --dry-run gemeldet hat, und halt dann an. Ein echter Lauf kostet sofort und hat keine eigene Bestätigungsabfrage, also warte auf die ausdrückliche Zustimmung des Menschen. Nutze --prune nie, außer der Mensch hat es verlangt.
7. Nach der Zustimmung übersetzen
npx @verbatra/cli translate --jsonMelde die Listen succeeded, partial und failed aus der Zusammenfassung. Eine Locale mit partial oder failed behält, was gelungen ist.
8. Committen und verbinden
Committe verbatra.config.ts, .env.example, falls vorhanden, die Anweisungsdatei und die Client-Konfigurationen aus Schritt 3, verbatra.lock.json, verbatra.provenance.json, sobald ein Lauf sie geschrieben hat, und die übersetzten Locale-Dateien. Committe nie .env, .env.local, .verbatra-local/ oder verbatra.cache.json; prüf, dass die .gitignore sie abdeckt.
Sag dem Menschen dann, dass er seinen Client neu starten und den Server verbatra des Projekts bestätigen soll. Installiere in Claude Code nicht zusätzlich das verbatra-Plugin, das ihn ein zweites Mal registriert; claude mcp list zeigt die Verbindung. Ein Client, den init nicht erkannt hat, bekommt seinen einen Eintrag aus Einen MCP-Client verbinden.
Weiter
Einen MCP-Client verbinden
Der eine Eintrag, den jeder Client außer Claude Code braucht, und wie du den Agenten Geld ausgeben lässt.
Rezepte für Agenten und Skripte
Der --json-Envelope und die Exit-Codes, auf die sich die Befehle dieses Prompts selbst stützen, um darauf eigene Agenten-Loops aufzubauen.
Studio mit einem Browser-Agenten steuern
Eine andere Oberfläche, um ein bereits eingerichtetes Projekt aus einem Browser-Tab statt aus einer Shell zu steuern.
Schnellstart
Derselbe Einrichtungsweg, geschrieben für einen Menschen statt für einen Agenten.
Die Lock-Datei
Die vollen Details hinter dem Sicherheitsverhalten bei der Übernahme, auf das sich dieser Prompt stützt.