verbatra mit einem KI-Agenten einrichten

You are setting up verbatra (an i18n translation automation CLI, `@verbatra/cli`
on npm) in this project. This project already has an existing i18n setup - do not
treat it as a greenfield project. Follow these steps in order and do not skip the
safety gates in steps 7 and 8.

## 1. Inspect the existing i18n setup

Before touching anything, find out what is already here:

- Look in `package.json` dependencies for an i18n library: `i18next`, `vue-i18n`,
  `next-intl`, or `@ngx-translate/core`.
- Find the actual locale files (commonly under `locales/`, `src/locales/`,
  `public/locales/`, `i18n/`, or similar) and determine:
  - The file format: nested JSON, flat JSON, `.yml`/`.yaml`, `.xlf`/`.xliff`, `.arb`,
    or `.properties`.
  - The source locale: the language the strings are actually written in.
  - Every target locale already present.
  - The exact path pattern, written with a `{locale}` token, for example
    `locales/{locale}.json`, `src/i18n/{locale}/common.json`, or
    `res/{locale}/strings.xml`.
- Map what you found to one verbatra format id: i18next -> `i18next-json`,
  vue-i18n -> `vue-i18n-json`, next-intl -> `next-intl-json`,
  ngx-translate -> `ngx-translate-json`, `.yml`/`.yaml` -> `yaml`,
  `.xlf`/`.xliff` -> `xliff`, `.arb` -> `arb`, `.properties` -> `properties`. Plain
  JSON with no matching library: pick by placeholder syntax, `{{name}}` means
  `i18next-json`, single-brace `{name}` means `vue-i18n-json`.
- If the format is `xliff`: verbatra only updates `<target>` elements in a file that
  already exists, it never creates one. Every target locale's XLIFF file must already
  be present before you run `translate`.

Do not trust `verbatra init`'s own format auto-detection: it only inspects
`package.json` for exactly one of `i18next`/`vue-i18n`/`next-intl`/
`@ngx-translate/core` and never reads the locale directory itself, so it cannot see
YAML, XLIFF, ARB, properties, or a project with more than one of those dependencies.
Use what you found above instead of trusting its guess.

## 2. Install the CLI

npm install --save-dev @verbatra/cli

pnpm and yarn work too. With pnpm, if it exits with `ERR_PNPM_IGNORED_BUILDS`, run
`pnpm approve-builds` once and approve neither entry.

## 3. Scaffold the config, non-interactively

Run `verbatra init` with explicit flags for what you found in step 1:

npx verbatra init --provider <anthropic|openai|gemini|deepl> --source <source-locale> \
  --targets <comma-separated-target-locales> --path <pattern-with-{locale}> --yes

Ask the human which provider to use unless it is already obvious from the project
(an existing key reference, a comment, a teammate's note). Do not pick a provider
that spends against a service the human never agreed to.

`init --provider` accepts only `anthropic`, `openai`, `gemini`, or `deepl`. For a
local or self-hosted OpenAI-compatible server instead, scaffold with one of those
four as a placeholder, then replace the whole `provider` block in
`verbatra.config.ts` by hand with an `openai-compatible` block (it needs `baseUrl`,
`model`, and `maxOutputTokens`); `doctor` in step 4 validates either shape the same
way.

`init` has no `--format` flag. Open the generated `verbatra.config.ts` right after
and set `format` to the id you determined in step 1 - the scaffold's own guess is
unreliable for anything beyond the four JSON dependencies, and is wrong outright for
YAML, XLIFF, ARB, and properties projects.

If the project splits strings across several namespace files per locale (for
example `common.json` and `auth.json` side by side), verbatra addresses exactly one
file per config: `files.pattern` is a literal path, never a glob. Tell the human
this project needs one config per namespace before you go further, and stop for
their direction rather than guessing which namespace to wire up.

## 4. Run doctor and fix until clean

npx verbatra doctor

`doctor` validates the config, the format, the provider id, and the source file,
with no network call and no key read. Fix whatever it reports by editing
`verbatra.config.ts` (for example a missing `model` and `maxTokens` for Anthropic,
or `model` and `maxOutputTokens` for OpenAI, Gemini, or openai-compatible), then run
it again. Repeat until it passes with no errors.

## 5. Add the API key variable name - never a value

cp .env.example .env

Open `.env` and confirm it names the right variable for the chosen provider
(`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or `DEEPL_API_KEY`). Do not
write, invent, or ask the human to paste a key value into anything you output.
Leave the value blank and tell the human to fill it in themselves, directly in
`.env`.

## 6. Preview - read-only, no spend

Run all three and read what they report:

npx verbatra check --json
npx verbatra diff --json
npx verbatra translate --dry-run --json

None of the three calls a provider, needs a key, or writes a file. `check` gives
per-locale counts, `diff` names the exact keys, and `translate --dry-run` gives the
full run summary a real run would produce.

Before you go further, know how verbatra treats what is already there: it never
overwrites or retranslates an existing value. A source key the target file already
has is left exactly as it is, even on this very first run before a lock file
exists - only keys genuinely missing from the target get translated. The one trap:
an empty string still counts as an existing key, so a placeholder value like `""`
will not be filled in by a normal run. If this project has empty-string
placeholders that need a real translation, tell the human and ask before deleting
those keys from the target files, since that changes tracked files; once deleted,
the next run treats them as missing and translates them.

## 7. Stop. Report. Get explicit confirmation.

Summarize in plain language: how many keys are pending, per locale, and what
`translate --dry-run` said it would do. Then stop and ask the human to explicitly
confirm before you run a real `translate`. Do not proceed on your own judgment: a
real run spends against the provider immediately, with no confirmation prompt of
its own.

Never suggest or use `--prune` unless the human has explicitly asked for orphaned
keys to be removed from target files. It deletes existing target entries.

## 8. Only after explicit confirmation: translate for real

npx verbatra translate --json

Report the result from the summary's `succeeded`, `partial`, and `failed` lists. A
`partial` or `failed` locale was still written with whatever did succeed; nothing
already translated is lost.

## 9. Commit the right files

Commit:
- `verbatra.config.ts`
- `.env.example`
- `verbatra.lock.json`
- the translated locale files

Never commit `.env`, `.env.local`, `.verbatra-local/`, or `verbatra.cache.json`.
`verbatra init` already added these to `.gitignore`; confirm they are actually
ignored before committing rather than assuming the scaffold caught every case.