Saltar al contenido
Saltar al contenido

Docs / Primeros pasos

Página traducida automáticamente

Esta página se tradujo automáticamente, así que puede contener errores o sonar un poco rara. La versión en inglés es la fuente de la verdad. Leer el original en inglés.

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

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

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 asigna a cada stack su id de formato y su estructura, Formatos 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

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

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 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 errorHaz esto
0Compara 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_AMBIGUOUSElige 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_OPTIONSEl mensaje nombra cada flag que aún falta.
2, CONFIG_EXISTSDile 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 documenta cada flag.

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

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

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

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

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.

Siguiente

Editar en GitHub

En esta página