Archivo de configuración

verbatra lee un único objeto de configuración pequeño y sin secretos, y lo valida antes de hacer ningún trabajo. Esta página es la referencia completa: cada clave, dónde puede vivir el archivo y cómo falla una configuración mala.

Una configuración mínima

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

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

defineConfig es un helper de identidad de @verbatra/sdk. Devuelve su argumento sin cambios y existe solo para darte inferencia de tipos y autocompletado en el editor.

Cada clave

Las claves de nivel superior desconocidas se rechazan. Por eso mismo una clave de API no puede vivir en la configuración: las claves vienen del entorno, no del archivo.

Locales y archivos

• sourceLocale debe ser una cadena no vacía.
• targetLocales debe contener al menos un locale, no debe incluir sourceLocale, y dos entradas no pueden ser iguales sin distinguir mayúsculas de minúsculas (por ejemplo ["de", "DE"] se rechaza), porque cada locale se convierte en el nombre de su propia hoja de Excel al exportar.
• format es uno de i18next-json, vue-i18n-json, next-intl-json, ngx-translate-json, xliff, yaml, arb o properties. Consulta Formatos.
• files.pattern debe contener el token {locale}, que verbatra reemplaza con cada locale: locales/{locale}.json se resuelve a locales/de.json. Las rutas se resuelven contra el directorio de trabajo.

provider

Un objeto seleccionado por id: anthropic, openai, gemini, deepl u openai-compatible. Cada proveedor toma sus propias options (modelo, límite de tokens y campos específicos del proveedor), y las claves de opción desconocidas se rechazan. Las opciones por proveedor están documentadas en Proveedores.

glossary

Un mapa de términos de origen a términos de destino preferidos, en línea o como ruta a un archivo JSON con la misma forma (un objeto plano de claves string a valores string):

export default defineConfig({
  // ...
  glossary: {
    "Sign in": "Anmelden",
  },
  // or: glossary: "glossary.json",
});

Las dos formas son mutuamente excluyentes; no hay fusión entre ellas. Una ruta de archivo relativa se resuelve contra el directorio del archivo de configuración cargado, o contra el directorio de trabajo cuando la configuración se pasa como override en memoria. El archivo debe estar codificado en UTF-8 y no superar 1 MiB, y se lee una vez cuando la configuración carga: verbatra no lo vigila en busca de cambios, así que edítalo y reinicia para recoger una actualización. Un archivo ausente, JSON inválido o un valor que no sea un mapa plano de strings hace fallar la carga de la configuración con CONFIG_INVALID, nombrando la ruta resuelta.

Cómo se aplica el glosario depende del proveedor: los proveedores LLM reciben el mapa resuelto con la solicitud y se les instruye para tratar sus términos como vinculantes, mientras que DeepL ignora un mapa de términos y aplica en su lugar un glosario configurado por id. Consulta Proveedores.

tone

Uno de "formal", "informal" o "neutral". Los proveedores LLM lo reciben con la solicitud y se les instruye para respetarlo; DeepL lo asigna a su ajuste de formalidad. Consulta Proveedores para los detalles por proveedor, incluida la degradación del nivel gratuito de DeepL.

prune

Desactivado por defecto. Cuando es true, las claves presentes en un archivo de destino pero ausentes del origen (las claves huérfanas del diff) se eliminan del archivo escrito y de el archivo de bloqueo. Solo se eliminan claves huérfanas, nunca otra cosa. Una opción prune por ejecución en translate (la opción --prune de la CLI) tiene prioridad sobre el valor de la configuración.

generatePlurals

Desactivado por defecto. Cuando es true, verbatra sintetiza las formas plurales CLDR que un idioma de destino requiere pero el origen no aporta (por ejemplo few y many en polaco). Soportado solo para proyectos i18next-JSON traducidos por un proveedor LLM; DeepL, los formatos que no son i18next y los idiomas de destino desconocidos recurren al aviso de plurales por locale. No hay opción de CLI, así que defínelo en la configuración; la entrada de translate() del SDK acepta un override de generatePlurals por ejecución que tiene prioridad.

maxBatchSize

Por defecto 50. Las entradas faltantes más las modificadas de un locale se dividen en sublotes secuenciales que no superan este tamaño, así que una solicitud sobredimensionada al proveedor no puede hacer fallar el locale entero. Un sublote fallido se retiene y se reintenta en la siguiente ejecución mientras los demás siguen avanzando. Debe ser un entero positivo; los valores cero, negativos o fraccionarios se rechazan. Solo por configuración: no hay opción de CLI ni override por ejecución.

maxTokens y budgetBehavior

maxTokens es un presupuesto de tokens para toda la ejecución: tokens de entrada más de salida, sumados a través de cada llamada al proveedor (traducción principal y generación de plurales por igual) y a través de cada locale de destino. Se comprueba después de cada sublote completado, nunca dentro de uno, así que el sublote cuya finalización cruza el techo ya fue enviado, se acepta con normalidad y sus tokens siguen contando: un tope blando a posteriori, no una comprobación previa dura. Solo por configuración, sin opción de CLI.

budgetBehavior decide qué pasa una vez alcanzado el techo:

• "warn" (el valor por defecto) señala el exceso y deja que la ejecución continúe exactamente como si no hubiera presupuesto configurado.
• "stop" retiene cada clave aún no intentada durante el resto de la ejecución: las candidatas restantes del locale actual, y las candidatas de cada locale de destino posterior por completo (su diff y su informe de huérfanas siguen corriendo; solo se salta la llamada al proveedor). Las claves retenidas conservan su hash anterior en el bloqueo y se reintentan automáticamente en la siguiente ejecución, igual que ya lo hace una llamada al proveedor fallida.

Que el presupuesto salte nunca cambia el código de salida del comando, con cualquiera de los dos comportamientos. budgetBehavior sin maxTokens se acepta y no tiene efecto. Contra un proveedor sin tokens (DeepL, que no informa de uso que medir) la salvaguarda se declara inerte (supported: false en el budget del resumen de la ejecución) en lugar de producir un salto falso.

Orden de descubrimiento

verbatra busca hacia arriba desde el directorio de trabajo y usa la primera fuente que encuentra. Que haya varias fuentes presentes no es un error; gana la primera coincidencia. El orden de búsqueda es:

1. package.json (una propiedad "verbatra")
2. .verbatrarc
3. .verbatrarc.json
4. .verbatrarc.yaml
5. .verbatrarc.yml
6. .verbatrarc.js
7. .verbatrarc.cjs
8. .verbatrarc.ts
9. verbatra.config.js
10. verbatra.config.cjs
11. verbatra.config.ts

Para cargar un archivo explícito en lugar de buscar, pasa --config <path>; una ruta relativa se resuelve contra el directorio de trabajo. En el SDK, un configOverride en memoria tiene prioridad sobre un configPath explícito, que a su vez tiene prioridad sobre la búsqueda. Consulta las Recetas del SDK.

El directorio de trabajo y .env

Ejecuta verbatra desde la raíz de tu proyecto, o pasa --cwd apuntando a ella. El directorio de trabajo es el ancla única de todo lo que verbatra resuelve: la búsqueda de configuración empieza ahí y sube, .env.local y .env se cargan desde ahí, y la ruta de cada archivo de locale se resuelve contra él. Mantener las tres cosas en el mismo sitio es lo que hace que un simple verbatra translate funcione.

La precedencia del entorno es, de mayor a menor: una variable ya definida en tu entorno real, luego .env.local, luego .env. Una variable ya presente nunca se sobrescribe.

Cuando la carga falla

La carga de la configuración falla con uno de dos códigos de error estructurados:

• CONFIG_NOT_FOUND: la búsqueda no encontró ninguna configuración en ninguno de los sitios de arriba, o la ruta explícita de --config no existe.
• CONFIG_INVALID: se encontró una configuración pero no se pudo usar. Esto cubre un archivo que no parsea, una configuración que falla la validación de esquema y una ruta de archivo de glosario que no se pudo resolver. El mensaje lista cada problema de validación con la ruta de su clave, y una clave de nivel superior no reconocida gana la pista de que las claves de API se leen del entorno, no de la configuración. Un error crudo del parser o del sistema de archivos nunca escapa.

La CLI informa de cualquiera de los dos fallos y sale con el código 2, el código de salida de errores de frontera. Consulta CI y códigos de salida.