---
title: "Configura verbatra con un agente de IA"
description: "Un prompt corto para que un agente de IA de código añada verbatra a un proyecto que ya usa i18n, con una confirmación humana antes de gastar nada."
type: "tutorial"
---
# Configura verbatra con un agente de IA

Un prompt corto para que un agente de IA de código añada verbatra a un proyecto que ya usa i18n, con una confirmación humana antes de gastar nada.

Esta página es para un proyecto que ya tiene archivos de locale en el repositorio. Pega el **Prompt para agentes IA** de arriba en Claude Code, Codex, Gemini CLI, Cursor o cualquier agente que ejecute comandos de shell. Sigue los pasos de abajo y te pregunta tres cosas:

- **Qué proveedor** usar, salvo que el proyecto lo deje claro.
- **La clave de API**: el agente deja su variable vacía en `.env` para que la rellenes y nunca te pide la clave.
- **El visto bueno** antes del primer `translate` real, que gasta en el acto.

## Los pasos que sigue el agente [#los-pasos-que-sigue-el-agente]

Agente: sigue estos pasos en orden y nunca te saltes la parada del paso 6.

### 1. Revisar la configuración existente [#1-revisar-la-configuración-existente]

Antes de cambiar nada, busca la biblioteca de i18n en `package.json` (como `i18next`, `vue-i18n` o `next-intl`) y los archivos de locale. Anota el locale de origen, cada locale de destino que ya exista y el patrón de ruta con un token `{locale}`, como `locales/{locale}.json`. [Elige tu stack](https://verbatra.kreitz-webdev.de/es/docs/pick-your-stack.md) asigna a cada stack su id de formato y su estructura, [Formatos](https://verbatra.kreitz-webdev.de/es/docs/formats.md) indica qué archivos ya tienen que existir. JSON sin biblioteca de i18n: los marcadores `{{name}}` indican `i18next-json`, y la llave simple `{name}` indica `vue-i18n-json`.

### 2. Instalar la CLI [#2-instalar-la-cli]

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

pnpm, yarn y bun también funcionan. No apruebes ningún script de instalación, ni en `pnpm approve-builds` ni en `allowScripts` de npm: verbatra no necesita ninguno.

### 3. Crear la config y los archivos del agente [#3-crear-la-config-y-los-archivos-del-agente]

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

Pregunta a la persona qué proveedor usar, salvo que el proyecto lo deje claro. Nunca elijas uno que gaste en un servicio que la persona no haya aceptado, y nunca pases un valor de clave a `init`. [Proveedores](https://verbatra.kreitz-webdev.de/es/docs/providers.md) lista los ids; `none` desactiva la traducción automática. `init` detecta el formato, el patrón de ruta y los locales, imprime un envoltorio JSON y nunca pregunta. `--agent` además escribe una sección de verbatra en `AGENTS.md` (o en `CLAUDE.md` cuando es el único archivo de instrucciones o ya contiene la sección de verbatra) y el servidor MCP de verbatra, con el gasto desactivado, en la config de cada cliente que detecta, el `.mcp.json` de Claude Code cuando encuentra Claude Code o ningún cliente; `result.agent.clients` lista los archivos.

| Código de salida y código de error | Haz esto |
| --- | --- |
| `0` | Compara `result.config` con el paso 1, empezando por cada entrada de `result.sources` que diga `default`; `result.config.files.localeStyle` solo aparece cuando los archivos no escriben los locales tal cual. Si algo está mal, vuelve a ejecutarlo con el `--format`, `--path`, `--source` o `--targets` correcto, más `--force`. |
| `2`, `FORMAT_AMBIGUOUS` o `LAYOUT_AMBIGUOUS` | Elige entre los `candidates` y vuelve a ejecutarlo con `--format` o `--path`. Archivos de namespace uno junto a otro: detente y pregunta a la persona, porque una config cubre un patrón de archivo. |
| `2`, `MISSING_OPTIONS` | El mensaje nombra cada flag que aún falta. |
| `2`, `CONFIG_EXISTS` | Dile a la persona qué proveedor usa la config existente y espera su confirmación. Después ejecuta `npx @verbatra/cli init --agent --json`, que conserva la config y añade solo los archivos del agente. Pregunta antes de pasar `--force`. |

[init](https://verbatra.kreitz-webdev.de/es/docs/cli/init.md#proveedores) documenta cada flag.

### 4. Dejar la clave de API a la persona [#4-dejar-la-clave-de-api-a-la-persona]

Sáltate este paso con el proveedor `none`. La variable de la clave está en `result.apiKeyEnvVar`; tras `CONFIG_EXISTS` es `null`, así que toma el nombre de la comprobación `api-key` fallida de `npx @verbatra/cli doctor --json`. Copia `.env.example` a `.env`, o crea `.env` si `init` no escribió ningún ejemplo, nombra ahí la variable con un valor vacío y dile a la persona que la rellene. Nunca escribas, inventes ni pidas un valor de clave. Sigue sin esperar.

### 5. Comprobar la configuración sin gastar [#5-comprobar-la-configuración-sin-gastar]

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

Ninguno de estos comandos llama a un proveedor, necesita una clave ni escribe un archivo. Corrige cada comprobación fallida de `doctor` que puedas en `verbatra.config.ts`; la comprobación `api-key` solo pasa cuando la persona ha puesto la clave, así que no entres en bucle con ella. En `check` o `diff`, la salida `1` (sin sincronizar) es lo esperado antes de una primera ejecución; solo la salida `2` es un problema de configuración. Con el proveedor `none`, `translate --dry-run` sale con `3` cuando quedan claves para un traductor humano. Solo se traducen las claves que faltan en el destino, y una cadena vacía cuenta como presente, así que pregunta antes de borrar claves de marcador con `""`.

### 6. Detenerse y preguntar [#6-detenerse-y-preguntar]

Resume cuántas claves quedan pendientes por locale y qué informó `translate --dry-run`, y detente. Una ejecución real gasta de inmediato y no tiene su propio aviso de confirmación, así que espera la aprobación explícita de la persona. Nunca uses `--prune` salvo que la persona lo haya pedido.

### 7. Traducir tras la aprobación [#7-traducir-tras-la-aprobación]

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

Informa de las listas `succeeded`, `partial` y `failed` del resumen. Un locale `partial` o `failed` conserva lo que salió bien.

### 8. Hacer commit y conectar [#8-hacer-commit-y-conectar]

Haz commit de `verbatra.config.ts`, `.env.example` si existe, el archivo de instrucciones y las configs de cliente del paso 3, `verbatra.lock.json`, `verbatra.provenance.json` cuando una ejecución lo haya escrito, y de los archivos de locale traducidos. Nunca hagas commit de `.env`, `.env.local`, `.verbatra-local/` ni `verbatra.cache.json`; confirma que `.gitignore` los cubre.

Después dile a la persona que reinicie su cliente y apruebe el servidor `verbatra` del proyecto. En Claude Code, que no instale además el plugin de verbatra, que lo registra por segunda vez; `claude mcp list` muestra la conexión. Un cliente que `init` no detectó toma su única entrada de [Conectar un cliente MCP](https://verbatra.kreitz-webdev.de/es/docs/connect-an-mcp-client.md).

## Siguiente [#siguiente]

<Cards>
  <Card title="Conectar un cliente MCP" href="https://verbatra.kreitz-webdev.de/es/docs/connect-an-mcp-client.md" description="La única entrada que necesita cada cliente que no sea Claude Code, y cómo dejar que el agente gaste." />
  <Card title="Recetas para agentes y scripts" href="https://verbatra.kreitz-webdev.de/es/docs/agent-recipes.md" description="El envoltorio --json y los códigos de salida en los que se apoyan los propios comandos de este prompt, para construir encima tus propios bucles de agente." />
  <Card title="Maneja Studio con un agente del navegador" href="https://verbatra.kreitz-webdev.de/es/docs/agent-tools-in-studio.md" description="Una superficie distinta, para manejar un proyecto ya configurado desde una pestaña del navegador en lugar de una shell." />
  <Card title="Inicio rápido" href="https://verbatra.kreitz-webdev.de/es/docs/quickstart.md" description="El mismo recorrido de configuración, escrito para una persona en lugar de un agente." />
  <Card title="El archivo de bloqueo" href="https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md" description="Todo el detalle detrás del comportamiento de seguridad de adopción en el que se apoya este prompt." />
</Cards>
