Tu primera traducción

Cinco pasos te llevan de un proyecto vacío a un archivo de locale traducido. Solo necesitas Node.js >=22.14.0 y una clave de API de un proveedor cuando quieras traducir de verdad. Los tres primeros pasos no cuestan nada y no necesitan ninguna cuenta.

1. Instala

verbatra es una dependencia de desarrollo:

npm install --save-dev @verbatra/cli

pnpm y yarn también funcionan. El paquete incluye el binario verbatra; ejecútalo a través de tu gestor de paquetes (npx verbatra ..., pnpm verbatra ... o yarn verbatra ...). Los bloques de código de abajo usan el nombre a secas.

pnpm pide un paso más. pnpm add -D @verbatra/cli instala bien, pero sale con 1 y ERR_PNPM_IGNORED_BUILDS, y deja un pnpm-workspace.yaml sin responder con el que cualquier comando pnpm posterior del proyecto falla igual. Ejecuta pnpm approve-builds una vez y no apruebes ninguna de las dos entradas, o consulta la Solución de problemas para la solución no interactiva.

2. Genera una configuración

verbatra init --provider gemini

Con una terminal conectada, init pregunta por todo lo que no pasaste como opción, cada cosa con un valor por defecto:

• el proveedor: uno de anthropic, openai, gemini o deepl (opción --provider, la única entrada sin valor por defecto)
• el locale de origen, por defecto en (--source)
• los locales de destino, separados por comas, por defecto de (--targets)
• el patrón de archivos de locale, por defecto locales/{locale}.json (--path)

Pasa --yes para saltarte las preguntas y aceptar los valores por defecto. Sin una terminal (en CI, por ejemplo) init nunca pregunta; usa los valores por defecto y solo exige --provider.

init escribe tres cosas:

• verbatra.config.ts: la configuración de tu proyecto, validada contra el esquema real antes de escribirse
• .env.example: nombra la variable de la clave del proveedor, nunca el valor de una clave
• entradas en .gitignore para .env, .env.local, .verbatra-local/ y verbatra.cache.json, creadas o añadidas para que una clave real, el estado local o la caché regenerable nunca acaben en un commit

Volver a ejecutar init se salta los archivos que ya existen; --force los sobrescribe. También rellena format mirando tus dependencias: un proyecto que usa i18next, vue-i18n, next-intl o @ngx-translate/core recibe el formato JSON correspondiente, y cualquier otro toma por defecto i18next-json con un comentario TODO para cambiarlo. Para Gemini el resultado es este:

import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de"],
  format: "i18next-json",
  files: {
    pattern: "locales/{locale}.json",
  },
  provider: {
    id: "gemini",
    options: {
      model: "gemini-2.5-flash",
      maxOutputTokens: 4096,
    },
  },
});

3. Previsualiza sin clave de API

Si todavía no tienes un archivo de origen, crea uno en el patrón configurado, por ejemplo locales/en.json:

{
  "greeting": "Hello, {{name}}!",
  "cart": {
    "empty": "Your cart is empty."
  }
}

Ahora previsualiza la ejecución:

verbatra translate --dry-run

Una ejecución en seco no construye ningún proveedor, así que no necesita clave de API y no puede gastar nada. Lee tus archivos, los compara e imprime el mismo resumen por locale que una ejecución real, sin enviar una sola cadena ni escribir un solo archivo. Úsala para confirmar que el formato, el patrón de archivos y los locales son correctos antes de registrarte en ningún sitio.

verbatra check y verbatra diff también prescinden del proveedor: check informa de los recuentos por locale, diff lista las claves exactas.

4. Define tu clave de API

Las claves vienen del entorno, nunca del archivo de configuración. Cada proveedor alojado lee exactamente una variable; para Gemini es GEMINI_API_KEY. Copia el ejemplo generado y rellena tu clave:

cp .env.example .env

Luego abre .env y pega tu clave después de GEMINI_API_KEY=. translate, watch y studio cargan .env.local y luego .env desde el directorio de trabajo antes de una ejecución, y una variable ya definida en tu shell siempre gana. Consulta Proveedores para ver la variable de cada proveedor.

5. Traduce

Con la clave ya puesta, ejecuta el mismo comando de verdad:

verbatra translate

verbatra lee el locale de origen, ve que todas las claves faltan en de, las envía al proveedor en lotes, pasa cada resultado por la puerta de integridad, y escribe locales/de.json. La ejecución termina con un resumen por locale: claves traducidas, claves sin cambios, claves huérfanas y cualquier aviso. El código de salida es 0 cuando todos los locales quedaron completos y 1 cuando uno falló o quedó parcial (escrito, pero con claves aún faltantes); añade --json para un resumen legible por máquina.

Qué acaba de pasar

Ahora hay tres cosas en disco:

• locales/de.json: el archivo del locale de destino. Tiene las mismas claves que tu origen, en el mismo orden del documento, y {{name}} sobrevivió intacto a la traducción; un resultado que lo hubiera perdido se habría retenido, no escrito.

• verbatra.lock.json: el archivo de bloqueo. Para cada locale de destino asocia cada clave traducida con un hash de la cadena de origen de la que salió esa traducción:

  {
    "version": 1,
    "locales": {
      "de": {
        "cart.empty": "<source content hash>",
        "greeting": "<source content hash>"
      }
    }
  }

• .verbatra-local/: estado local del proceso (la instantánea de estado de la ejecución y los bloqueos de escritura por locale). init lo añadió a .gitignore; nunca lo confirmes.

El archivo de bloqueo es la línea base de todas las ejecuciones futuras. Ejecuta verbatra translate de nuevo sin editar nada y no se envía nada: todas las claves ya están al día. Edita una cadena de origen y solo esa clave se retraduce.

Siguiente

• Añade un idioma: suma un nuevo locale de destino a esta configuración.
• Cómo funciona: la canalización completa detrás de una ejecución.
• Archivo de configuración: todo lo que puede contener verbatra.config.ts.