Skip to content
Skip to Content

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 .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

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/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

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 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 codeDo this
0Compare 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_AMBIGUOUSPick 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_OPTIONSThe message names every flag still needed.
2, CONFIG_EXISTSTell 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_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

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

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

Report 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

Edit on GitHub

On this page