Saltar al contenido

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/compiler
npx verbaly init

Después agrega el plugin a tu config de Vite:

vite.config.ts
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

Servidor de dev

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.

import { t, verbaly, setLocale, getLocale, subscribe } from 'verbaly/app';

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

// 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 'verbaly/app';
adoptPage({ root: nextDocument, path: nextUrl.pathname });

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:

main.ts
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/compiler
npx verbaly init
webpack.config.mjs
import { 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 too

Está 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.

↑↓para moverteEnterpara abrir
Copiado en el portapapeles