---
title: "verbatra mit einem KI-Agenten einrichten"
description: "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."
type: "tutorial"
---
# 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 [#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 [#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](https://verbatra.kreitz-webdev.de/de/docs/pick-your-stack.md) ordnet jedem Stack seine Format-ID und sein Layout zu, [Formate](https://verbatra.kreitz-webdev.de/de/docs/formats.md) 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 [#2-die-cli-installieren]

```bash
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 [#3-konfiguration-und-agenten-dateien-anlegen]

```bash
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](https://verbatra.kreitz-webdev.de/de/docs/providers.md) 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_AMBIGUOUS` oder `LAYOUT_AMBIGUOUS` | 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_OPTIONS` | Die Meldung nennt jedes noch fehlende Flag. |
| `2`, `CONFIG_EXISTS` | 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](https://verbatra.kreitz-webdev.de/de/docs/cli/init.md#provider) beschreibt jedes Flag.

### 4. Den API-Key dem Menschen überlassen [#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 [#5-das-setup-ohne-kosten-prüfen]

```bash
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 [#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 [#7-nach-der-zustimmung-übersetzen]

```bash
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 [#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](https://verbatra.kreitz-webdev.de/de/docs/connect-an-mcp-client.md).

## Weiter [#weiter]

<Cards>
  <Card title="Einen MCP-Client verbinden" href="https://verbatra.kreitz-webdev.de/de/docs/connect-an-mcp-client.md" description="Der eine Eintrag, den jeder Client außer Claude Code braucht, und wie du den Agenten Geld ausgeben lässt." />
  <Card title="Rezepte für Agenten und Skripte" href="https://verbatra.kreitz-webdev.de/de/docs/agent-recipes.md" description="Der --json-Envelope und die Exit-Codes, auf die sich die Befehle dieses Prompts selbst stützen, um darauf eigene Agenten-Loops aufzubauen." />
  <Card title="Studio mit einem Browser-Agenten steuern" href="https://verbatra.kreitz-webdev.de/de/docs/agent-tools-in-studio.md" description="Eine andere Oberfläche, um ein bereits eingerichtetes Projekt aus einem Browser-Tab statt aus einer Shell zu steuern." />
  <Card title="Schnellstart" href="https://verbatra.kreitz-webdev.de/de/docs/quickstart.md" description="Derselbe Einrichtungsweg, geschrieben für einen Menschen statt für einen Agenten." />
  <Card title="Die Lock-Datei" href="https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md" description="Die vollen Details hinter dem Sicherheitsverhalten bei der Übernahme, auf das sich dieser Prompt stützt." />
</Cards>
