---
title: "Set up verbatra with an AI agent"
description: "A short prompt for an AI coding agent to add verbatra to a project that already has an i18n setup, with a human confirmation before it spends anything."
type: "tutorial"
---
# Set up verbatra with an AI agent

A short prompt for an AI coding agent to add verbatra to a project that already has an i18n setup, with a human confirmation before it spends anything.

This page is for a project that already has committed locale files. Paste the **Prompt for AI agents** above into Claude Code, Codex, Gemini CLI, Cursor, or any agent that runs shell commands. It follows the steps below and asks you three things:

- **Which provider** to use, unless the project makes it obvious.
- **The API key**: the agent leaves its variable blank in `.env` for you to fill in and never asks for the key.
- **The go-ahead** before the first real `translate`, which spends at once.

## The steps the agent follows [#the-steps-the-agent-follows]

Agent: follow these steps in order, and never skip the stop in step 6.

### 1. Inspect the existing setup [#1-inspect-the-existing-setup]

Before you change anything, find the i18n library in `package.json` (such as `i18next`, `vue-i18n`, or `next-intl`) and the locale files. Note the source locale, every target locale already present, and the path pattern with a `{locale}` token, such as `locales/{locale}.json`. [Pick your stack](https://verbatra.kreitz-webdev.de/docs/pick-your-stack.md) maps each stack to its format id and layout; [Formats](https://verbatra.kreitz-webdev.de/docs/formats.md) says which files must already exist. Plain JSON with no i18n library: `{{name}}` placeholders mean `i18next-json`, single-brace `{name}` means `vue-i18n-json`.

### 2. Install the CLI [#2-install-the-cli]

```bash
npm install --save-dev @verbatra/cli
```

pnpm, yarn, and bun work too. Approve no install scripts, neither in `pnpm approve-builds` nor in npm's `allowScripts`: verbatra needs none.

### 3. Scaffold the config and the agent files [#3-scaffold-the-config-and-the-agent-files]

```bash
npx @verbatra/cli init --provider <provider> --yes --json --agent
```

Ask the human which provider to use unless the project makes it obvious. Never pick one that spends against a service the human did not agree to, and never pass a key value to `init`. [Providers](https://verbatra.kreitz-webdev.de/docs/providers.md) lists the ids; `none` turns machine translation off. `init` detects the format, path pattern, and locales, prints one JSON envelope, and never prompts. `--agent` also writes a verbatra section to `AGENTS.md` (or to `CLAUDE.md` when that is the only instruction file or already holds the verbatra section) and the verbatra MCP server, spending off, to the config of each client it detects, Claude Code's `.mcp.json` when it finds Claude Code or no client at all; `result.agent.clients` lists the files.

| Exit code and error code | Do this |
| --- | --- |
| `0` | Compare `result.config` with step 1, starting with every `result.sources` entry that says `default`; `result.config.files.localeStyle` appears only when the files do not spell locales as written. If something is wrong, run it again with the right `--format`, `--path`, `--source`, or `--targets`, plus `--force`. |
| `2`, `FORMAT_AMBIGUOUS` or `LAYOUT_AMBIGUOUS` | Pick from `candidates` and run it again with `--format` or `--path`. Namespace files side by side: stop and ask the human, since one config covers one file pattern. |
| `2`, `MISSING_OPTIONS` | The message names every flag still needed. |
| `2`, `CONFIG_EXISTS` | Tell the human which provider the existing config uses and wait for their confirmation. Then run `npx @verbatra/cli init --agent --json`, which keeps the config and adds only the agent files. Ask before you pass `--force`. |

[init](https://verbatra.kreitz-webdev.de/docs/cli/init.md#providers) documents every flag.

### 4. Leave the API key to the human [#4-leave-the-api-key-to-the-human]

Skip this step for provider `none`. The key variable is `result.apiKeyEnvVar`; after `CONFIG_EXISTS` it is `null`, so take the name from the failing `api-key` check of `npx @verbatra/cli doctor --json`. Copy `.env.example` to `.env`, or create `.env` if `init` wrote no example, name the variable there with a blank value, and tell the human to fill it in. Never write, invent, or ask for a key value. Carry on without waiting.

### 5. Check the setup without spending [#5-check-the-setup-without-spending]

```bash
npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --json
```

None of these calls a provider, needs a key, or writes a file. Fix every failing `doctor` check you can in `verbatra.config.ts`; the `api-key` check passes only once the human has set the key, so do not loop on it. From `check` or `diff`, exit `1` (out of sync) is expected before a first run; only exit `2` is a setup problem. With provider `none`, `translate --dry-run` exits `3` when keys are left for a human translator. Only keys missing from a target get translated, and an empty string counts as present, so ask before you delete placeholder `""` keys.

### 6. Stop and ask [#6-stop-and-ask]

Summarize how many keys are pending per locale and what `translate --dry-run` reported, then stop. A real run spends at once and has no confirmation prompt of its own, so wait for the human's explicit go-ahead. Never use `--prune` unless the human asked for it.

### 7. Translate after the go-ahead [#7-translate-after-the-go-ahead]

```bash
npx @verbatra/cli translate --json
```

Report the summary's `succeeded`, `partial`, and `failed` lists. A `partial` or `failed` locale keeps what succeeded.

### 8. Commit and connect [#8-commit-and-connect]

Commit `verbatra.config.ts`, `.env.example` if it exists, the instruction file and the client config files from step 3, `verbatra.lock.json`, `verbatra.provenance.json` once a run has written it, and the translated locale files. Never commit `.env`, `.env.local`, `.verbatra-local/`, or `verbatra.cache.json`; confirm that `.gitignore` covers them.

Then tell the human to restart their client and approve the project's `verbatra` server. In Claude Code, do not also install the verbatra plugin, which registers it twice; `claude mcp list` shows the connection. A client `init` did not detect takes its one entry from [Connect an MCP client](https://verbatra.kreitz-webdev.de/docs/connect-an-mcp-client.md).

## Next [#next]

<Cards>
  <Card title="Connect an MCP client" href="https://verbatra.kreitz-webdev.de/docs/connect-an-mcp-client.md" description="The one entry each client other than Claude Code needs, and how to let the agent spend." />
  <Card title="Recipes for agents and scripts" href="https://verbatra.kreitz-webdev.de/docs/agent-recipes.md" description="The --json envelope and exit codes this prompt's own commands rely on, for building your own agent loops on top." />
  <Card title="Drive Studio with a browser agent" href="https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio.md" description="A different surface, for driving an already-set-up project from a browser tab instead of a shell." />
  <Card title="Quickstart" href="https://verbatra.kreitz-webdev.de/docs/quickstart.md" description="The same setup walkthrough, written for a person instead of an agent." />
  <Card title="The lock file" href="https://verbatra.kreitz-webdev.de/docs/the-lock-file.md" description="The full detail behind the adoption-safety behavior this prompt relies on." />
</Cards>
