Referencia

Configuración

Un fichero en la raíz de tu proyecto, y el plugin toma el mismo objeto, así que una opción significa lo mismo para tu build que para la línea de comandos. Los flags ganan sobre el fichero.

verbaly.config.mjs

export default {
  sourceLocale: 'es',
  locales: ['es', 'en', 'pt'],
};

Los nombres aceptados son verbaly.config.js, .mjs, .ts, .mts y .json, leídos en ese orden. Un config en TypeScript necesita esbuild instalado, y la herramienta te lo dice si falta.

Todas las opciones

Opción	Por defecto	Qué hace
`sourceLocale`	`'en'`	El idioma en el que escribes
`locales`	Los catálogos que encuentra	Tus idiomas. Si los listas, la lista está completa; si no la pones, cada fichero JSON de `dir` cuenta como uno
`dir`	`'locales'`	Dónde viven los catálogos
`root`	Donde ejecutaste el comando	La raíz del proyecto contra la que se resuelven las demás rutas
`include`	`src/`, `app/`	Qué ficheros se escanean buscando mensajes. `[]` apaga el escaneo, para un proyecto cuyos catálogos se escriben a mano
`exclude`	`node_modules`, `dist`	Qué ficheros se saltan dentro de eso
`routing`	Sigue tu setup	Dónde vive el idioma en tus direcciones. Ver Estrategia de URLs
`dts`	`'verbaly.d.ts'`	Dónde se escriben los tipos generados, o `false` para no escribir ninguno. Astro y Nuxt los colocan en su propia carpeta de tipos sin que tú pongas esto
`bundle`	Nada excluido	`exclude`: grupos de mensajes que se quedan en el build y nunca llegan al navegador
`render`	Apagado	El mirror pre-traducido para sitios estáticos. Sus opciones están más abajo
`translate`	Claude	Todo lo que la traducción automática necesita más allá del proveedor: modelo, tamaño de lote, glosario, instrucciones
`icu`	Lo deciden tus catálogos	Fuerza que el parser de ICU viaje. Solo para mensajes que llegan a tu app después del build
`relative`	Lo deciden tus catálogos	Lo mismo, para el formato de tiempo relativo

Dentro de render

Solo para sitios estáticos que publican un árbol de direcciones por idioma. Añadir esta sección es lo que enciende el mirror.

Opción	Qué hace
`baseUrl`	Tu dirección pública. Los alternates y el sitemap la necesitan
`site`	El directorio construido que se mirrorea. Por defecto `dist`
`sitemap`	Escribe un sitemap por idioma. Una cadena le pone nombre al fichero
`exclude`	Páginas a dejar fuera de ese sitemap, por ruta dentro del directorio de build
`hreflang`	Alternates recíprocos en cada página. Encendido por defecto
`redirect`	Manda a quien llega por primera vez a su idioma antes de que la página pinte
`links`	Las direcciones reales detrás de los links con nombre dentro de tus mensajes
`base`	El prefijo de ruta, si tu sitio no se sirve desde la raíz
`attribute`	El atributo que hay que buscar, si renombraste `data-verbaly`
`inlineCatalog`	Escribe en cada página los mensajes que renderiza, así no se baja ningún otro
`clean`	Borra páginas de idioma que dejó un build anterior

Dentro de translate

Todo lo que la traducción automática necesita más allá del proveedor, para que una ejecución se comporte igual para todo el equipo en vez de depender de quién escribió el comando.

Opción	Qué hace
`model`	Qué modelo usa el proveedor incluido. `--model` lo cambia para una sola corrida
`batchSize`	Cuántos mensajes van en una petición, 20 por defecto. Bájalo si los mensajes largos salen cortados, súbelo si son cortos
`concurrency`	Cuántas peticiones van a la vez, 4 por defecto. Bájalo si tu proveedor te limita el ritmo
`retries`	Cuántas veces se reintenta una petición que falló por algo pasajero, 2 por defecto
`instructions`	Lo mismo que le contarías a una persona que traduce tu producto: cuánta formalidad usar, cuán corta tiene que quedar la etiqueta de un botón, qué es tu aplicación
`glossary`	Cómo tiene que salir un término. Das una forma para todos los idiomas, que es como se dice deja esto en paz, o una por idioma. Solo se envían los términos que el lote realmente contiene

Una corrida sobrevive a una mala conexión. Las peticiones que fallan por algo pasajero se reintentan, y si aun así una no vuelve, todo lo demás queda escrito y el informe nombra los mensajes que no pudo llenar. Volver a correr translate pide solo esos, así que una conexión caída nunca te cuesta la corrida entera dos veces. El comando termina con 1 cuando pasa, para que un script se entere.

Solo en el plugin

failOnMissing: false deja que un build termine con mensajes sin traducir, que caen a tu idioma fuente. Nunca deja pasar una traducción rota: una que perdió un valor o un caso del plural sigue parando el build, porque renderizaría mal.