Zum Inhalt springen
Zum Inhalt springen

Docs / Erste Schritte

Maschinell übersetzte Seite

Diese Seite wurde automatisch übersetzt und kann daher Fehler oder seltsame Formulierungen enthalten. Die englische Version ist die maßgebliche Quelle. Das englische Original lesen.

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 .env leer, 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/cli

pnpm, 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 --agent

Frag 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 FehlercodeTu das
0Vergleiche 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_AMBIGUOUS oder LAYOUT_AMBIGUOUSWä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_OPTIONSDie Meldung nennt jedes noch fehlende Flag.
2, CONFIG_EXISTSSag 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_EXISTS 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 --json

Keiner 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 --json

Melde 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

Auf GitHub bearbeiten

Auf dieser Seite