Tu primera traducción

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

1. Instala

verbatra es una dependencia de desarrollo:

pnpm add -D @verbatra/cli

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

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 y .verbatra-local/, creadas o añadidas para que una clave real o el estado local 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. 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=. verbatra carga .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.

4. Traduce

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

Luego ejecuta:

verbatra translate

verbatra lee el locale de origen, ve que todas las claves faltan en de, las envía al proveedor en lotes, comprueba en cada resultado la integridad de los marcadores de posición e ICU, 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 tuvieron éxito y 1 cuando uno falló; 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. Para previsualizar cualquier ejecución sin una llamada al proveedor ni una sola escritura, usa verbatra translate --dry-run.

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.