Integraciones
Plugin de Vite
El plugin oficial de Vite. Extrae tus textos mientras escribes, da a cada idioma su propia descarga y lista lo que falta en cada build.
Instalación
Agrega el runtime y este plugin, y después el compilador, que es donde vive el comando verbaly. init escribe tu config y tu catálogo fuente.
pnpm add verbaly @verbaly/vite pnpm add -D @verbaly/compilerDespués agrega el plugin a tu config de Vite:
import verbaly from '@verbaly/vite';
export default { plugins: [verbaly()] };Las opciones son las mismas que la config del CLI: sourceLocale, locales, dir, include, exclude, root. Escríbelas en tu verbaly.config, donde también las leen verbaly check y verbaly extract. Una opción pasada al plugin gana sobre el archivo, y esos dos comandos nunca la leen, así que el build avisa.
Cómo compila
t`Hola ${name}`se convierte ent("x7Ka9q2f", { "name": name }), donde la clave es el hash del contenido, estable entre archivos.- El idioma fuente va con tu app. Cada uno de los demás es su propio archivo, que se descarga la primera vez que
setLocale()lo pide. - Los catálogos siguen siendo JSON plano: sin formato propietario, portables a cualquier TMS.
- Esto cubre también archivos
.svelte,.vuey.astro: bloques de script y markup, incluida la forma de store$tde Svelte y el frontmatter de Astro. - Un archivo que importa
@verbaly/react,@verbaly/vueo@verbaly/sveltetambién cargaverbaly/app, así queuseT()encuentra su instancia en una app de una sola página sin provider encima.
Servidor de dev
- Los textos nuevos se extraen mientras escribes. Catálogos y tipos se actualizan un momento después de que pares, y la página se recarga.
- La primera escritura toma los textos de cada archivo de tu
include, abierto o no, como haceextract. liveExtraction: falseevita que el servidor de desarrollo escriba tus archivos de traducción: los textos nuevos se siguen pintando desde memoria, como en un build, ynpx verbaly extractlos escribe cuando tú decides.- Editar un catálogo a mano lo recarga. Un texto que es de tu código vuelve a su sitio, y la terminal nombra el archivo y la línea donde vive. Cada escritura parte de los archivos en disco, así que un checkout nunca se deshace con un texto anterior, y un catálogo guardado a medio escribir se reporta en una línea mientras el servidor sigue funcionando.
- La terminal nombra cada una de estas cosas una vez: una clave escrita con dos textos, un
tcon otro nombre, una traducción más vieja que su texto fuente. - Cuando arranca el servidor de desarrollo o el build, nombra una vez cada archivo fuera de tu
includeque escribet`…`, con el patrón que hay que añadir: ese texto nunca se extrae, así que saldría en tu idioma fuente en todas partes.
Build
El módulo del proyecto
verbaly/app es el módulo propio de tu proyecto: el plugin lo escribe a partir de tu config y tus catálogos, así que tus idiomas, tu modo de URL y tus textos de origen ya están dentro. También responde a virtual:verbaly, que es el mismo módulo, salvo con webpack, que lee ese prefijo como un esquema de URL: ahí, importa verbaly/app.
Los t y verbaly compartidos son para el navegador. En el servidor, createRequestInstance(locale) construye una instancia nueva por petición y espera su catálogo antes de devolver, así que la página llega traducida. createInstance(options) queda para montajes propios (mira Server-side).
adoptPage existe cuando render.inlineCatalog está encendido. Cada página lleva solo los mensajes que muestra, así que un router que cambia de documento tiene que entregar los de la siguiente: llámalo desde el hook que dispara antes del cambio. El <ClientRouter /> de Astro ya viene cableado.
Los tipos generados viven en src/verbaly.d.ts (la raíz si no hay src/), la carpeta que el tsconfig de las plantillas de Vite y SvelteKit ya lee, y tipan este módulo: las claves autocompletan y los params de cada clave se exigen. El servidor de desarrollo, cada vite build y lo que cargue tu config de Vite, como svelte-check o Vitest, escriben los mismos tipos. Un script que corre tsc antes del build los escribe primero con npx verbaly typegen en un clon fresco. Muévelos o apágalos con la opción dts del config.
El idioma que eligió un visitante
switchLocale y el useLocale de cada paquete de framework guardan la elección en el navegador, y ellos y setLocale escriben <html lang> y <html dir>. Una app de una sola página arranca en su idioma fuente, así que recupera la elección antes del primer render:
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
// the saved choice, else the browser's, loaded before anything renders
setLocale(resolveLocale({ supported: locales, path: false })).then(render);Una app renderizada en servidor cambia de idioma con switchLocale o useSwitchLocale, que además escriben la cookie que lee el servidor.
¿No usas Vite? Usa @verbaly/unplugin
@verbaly/unplugin lleva el mismo compilador a webpack 5, Rollup, esbuild y Rspack: el módulo tipado verbaly/app, la transformación de las plantillas etiquetadas y el reporte del build, que dice cada problema una vez aunque un watch recompile (failOnMissing: true para el build en su lugar).
En la instalación ocupa el lugar del plugin de Vite:
pnpm add verbaly @verbaly/unplugin pnpm add -D @verbaly/compilerimport { verbaly } from '@verbaly/unplugin';
export default { plugins: [verbaly.webpack()] };
// also: verbaly.rollup() · verbaly.esbuild() · verbaly.rspack()
// languages live in your verbaly.config, where verbaly check reads them tooEstá enfocado al build: corre npx verbaly extract en tu dev loop o CI, ya que la extracción en vivo y la recarga mientras escribes solo vienen con el plugin de Vite. Cada build escribe también los tipos, así que un clon fresco pasa el typecheck tras su primer build. Solo ESM, como el compilador (usa webpack.config.mjs).
El módulo del proyecto es el mismo aquí, así que la línea de arranque de arriba recupera el idioma que eligió un visitante. Un archivo que importa @verbaly/react, @verbaly/vue o @verbaly/svelte también lo carga, así que sus hooks funcionan sin provider en el navegador.