Docs / Get started
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
.envfor 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
Agent: follow these steps in order, and never skip the stop in step 6.
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 maps each stack to its format id and layout; Formats 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
npm install --save-dev @verbatra/clipnpm, 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
npx @verbatra/cli init --provider <provider> --yes --json --agentAsk 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 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_ or LAYOUT_ | 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_ | The message names every flag still needed. |
2, CONFIG_ | 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 documents every flag.
4. Leave the API key to the human
Skip this step for provider none. The key variable is result.apiKeyEnvVar; after CONFIG_ 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
npx @verbatra/cli doctor --json
npx @verbatra/cli check --json
npx @verbatra/cli diff --json
npx @verbatra/cli translate --dry-run --jsonNone 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
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
npx @verbatra/cli translate --jsonReport the summary's succeeded, partial, and failed lists. A partial or failed locale keeps what succeeded.
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.
Next
Connect an MCP client
The one entry each client other than Claude Code needs, and how to let the agent spend.
Recipes for agents and scripts
The --json envelope and exit codes this prompt's own commands rely on, for building your own agent loops on top.
Drive Studio with a browser agent
A different surface, for driving an already-set-up project from a browser tab instead of a shell.
Quickstart
The same setup walkthrough, written for a person instead of an agent.
The lock file
The full detail behind the adoption-safety behavior this prompt relies on.