Plugin de Vite

import verbaly from '@verbaly/vite';

export default { plugins: [verbaly({ sourceLocale: 'es' })] };

Las opciones son las mismas que la config del CLI: sourceLocale, locales, dir, include, exclude, root. Las opciones inline ganan sobre el archivo de config.

Cómo compila

• t`Hola ${name}` se convierte en t("x7Ka9q2f", { "name": name }), donde la clave es el hash del contenido, estable entre archivos.
• El idioma fuente va inline; cada otro idioma se vuelve su propio chunk lazy, cargado en el primer setLocale().
• Los catálogos siguen siendo JSON plano: sin formato propietario, portables a cualquier TMS.
• Esto cubre también archivos .svelte, .vue y .astro: bloques de script y markup, incluida la forma de store $t de Svelte y el frontmatter de Astro.

Servidor de dev

• Los textos nuevos se extraen mientras escribes; catálogos y tipos se actualizan con debounce, y el servidor dispara un reload completo.
• 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 t con 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 fichero fuera de tu include que escribe t`…`, 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 virtual

import { t, verbaly, setLocale, getLocale, subscribe } from 'virtual:verbaly';

// SSR: request-scoped instances + locale metadata
import { createRequestInstance, createInstance, loadMessages, locales, sourceLocale } from 'virtual:verbaly';

// fresh instance, catalog awaited, no flash. One call per request:
const v = await createRequestInstance(locale);

// raw catalog for a locale (SSR integrations serialize it to the client):
const messages = await loadMessages(locale);

// client-side routing over pre-translated pages (render.inlineCatalog):
import { adoptPage } from 'virtual:verbaly';
adoptPage({ root: nextDocument, path: nextUrl.pathname });

El singleton t/verbaly es para el browser. En el servidor, createRequestInstance(locale) construye una instancia fresca por request y espera su catálogo antes de devolver: el contrato no-FOUC en una llamada. createInstance(options) queda para setups custom (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. Un clon fresco los escribe con npx verbaly typegen antes de tsc. Muévelos o apágalos con la opción dts del config.

¿No usas Vite? Usa @verbaly/unplugin

@verbaly/unplugin lleva el mismo compilador a webpack 5, Rollup, esbuild y Rspack: el módulo tipado virtual:verbaly, 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).

import { verbaly } from '@verbaly/unplugin';

export default { plugins: [verbaly.webpack({ locales: ['en', 'es'] })] };
// also: verbaly.rollup(…) · verbaly.esbuild(…) · verbaly.rspack(…)

Está enfocado al build: corre npx verbaly extract en tu dev loop o CI, ya que la extracción en vivo y el HMR siguen siendo el valor de este plugin de Vite. Solo ESM, como el compilador (usa webpack.config.mjs).