Guías
En el servidor
El core corre donde corra JavaScript, incluido Node. Crea una instancia, pasa el locale, llama a t(). Sin DOM.
Una instancia por request
Construye una instancia nueva por request y pásale el locale del visitante. negotiateLocale lee el header Accept-Language y elige la mejor coincidencia entre tus locales (entiende los q-values, y es-PE coincide con es). resolveRequestLocale toma toda la decisión en una llamada: primero la dirección cuando lleva el idioma, luego la elección guardada, luego el navegador, luego tu fallback. Las instancias no comparten estado, así que dos requests nunca mezclan sus idiomas.
import { createVerbaly, negotiateLocale } from 'verbaly';
import es from './locales/es.json';
import en from './locales/en.json';
function handle(req) {
const locale = negotiateLocale(req.headers['accept-language'], ['en', 'es']);
const v = createVerbaly({ locale, fallback: 'en', messages: { en, es } });
return v.t('home.title');
}Cuando tus direcciones llevan el idioma
Si tus páginas viven en /es/dashboard, esa dirección es la respuesta. Quien abra el enlace recibe español, haya elegido idioma aquí o no, porque una dirección es pública y se comparte mientras que una elección guardada es de una sola persona. Una página sin prefijo pasa a significar tu idioma de origen, así que quien eligió español una vez no ve tus páginas en inglés traducidas por accidente.
Lo activas contándole a tu integración el routing que ya tienes puesto. Esto es todo, por stack:
| Stack | Qué escribes |
|---|---|
| SvelteKit | Pasa routing a verbalyHandle, y añade verbalyReroute en hooks.ts para que un solo árbol de rutas sirva todos los idiomas |
| Nuxt | Nada: el módulo lee la dirección por ti |
| Next.js | routing: 'prefix-all' en tu config, y setRequestLocale(locale) en tu layout [locale], antes de que nada pida texto |
| Astro | createRequestInstance(Astro.currentLocale ?? sourceLocale) en la página |
Tus páginas también pueden apuntarse entre ellas para los buscadores. alternateLinks te da la lista de direcciones de una página en todos los idiomas, la misma lista que recibe un sitio renderizado estáticamente, así que una página renderizada en servidor no es de segunda. Ver Estrategia de URL.
Renderiza el HTML por adelantado
Para sitios estáticos, verbaly render pre-llena tu HTML compilado por locale para que las páginas se sirvan ya traducidas. Ver CLI → Renderizado estático.
Meta-frameworks
En SvelteKit, Nuxt y Next.js no cableas nada de esto a mano. La integración de SvelteKit, el módulo de Nuxt y la integración de Next.js eligen el idioma por petición e hidratan sin parpadeo, todo sobre estas mismas primitivas.