Integraciones
Vue
El paquete oficial de Vue 3 para Verbaly. Composables con limpieza automática, un componente <Trans> para rich text, y claves + params totalmente tipados.
Qué puedes lograr:
- Traduce con composables (useT, useLocale) que reaccionan a cada cambio de idioma
- Enlaza el idioma directo a un select:
useLocale()devuelve un computed escribible - Mantén claves y params totalmente tipados, con autocompletado desde tus propios mensajes
- Cero fugas: las suscripciones son por componente y se limpian vía
onScopeDispose
Instalación
Agrega el runtime, este paquete y el plugin de Vite, 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/vue @verbaly/vite pnpm add -D @verbaly/compilerDespués agrega verbaly() a los plugins de vite.config. Escribe verbaly/app, el módulo que leen tus componentes.
En webpack, Rollup, esbuild o Rspack, instala @verbaly/unplugin en lugar de @verbaly/vite: otros bundlers enseña cómo.
Setup y composables
import { verbalyPlugin } from '@verbaly/vue';
import { verbaly } from 'verbaly/app';
app.use(verbalyPlugin(verbaly));<script setup>
import { useT, useLocale } from '@verbaly/vue';
const t = useT();
const locale = useLocale(); // writable: locale.value = 'en'
const count = 3;
</script>
<template>
<p>{{ t`You have ${count} messages` }}</p>
</template>- Las suscripciones son por componente y se limpian al desmontar vía
onScopeDispose. useLocale()devuelve un computed escribible, así que conéctalo directo a un select.- ¿Sin el plugin instalado, en el navegador?
useT()yuseLocale()leen la instancia que creaverbaly/app, y el plugin del bundler carga ese módulo en cada archivo que importa@verbaly/vue, así que una app de una sola página o un test de componente no necesitan preparación. En el servidor el plugin es obligatorio, porque cada petición tiene su propia instancia.
El idioma que elige un visitante
Escribir locale.value cambia todos los componentes, y la página lo sigue: <html lang>, <html dir> y la elección, guardada en el navegador. Una app de una sola página arranca en su idioma fuente, así que recupera esa elección antes de montar:
// the saved choice, else the browser's, loaded before anything renders
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
setLocale(resolveLocale({ supported: locales, path: false })).then(() => app.mount('#app'));Donde un servidor renderiza la página, como en Nuxt, cambia de idioma con switchLocale de verbaly/app: además escribe la cookie que lee el servidor.
Escribe el texto en su lugar
El compilador también lee tus archivos .vue: escribe el texto fuente en una interpolación, en un binding de directiva o en script setup, y se extrae, recibe su clave y sus tipos al guardar. El texto que solo se muestra nunca se extrae, así que una página puede enseñar t`…` como ejemplo sin riesgo. Sin inventar claves, sin tocar catálogos.
<template>
<p>{{ t`Hola ${user.name}` }}</p>
<a :title="t`Abrir ajustes`">…</a>
</template>
<!-- extracted on save; the build rewrites both to t('key', …) -->¿Prefieres claves legibles? t.id('inbox.title') antes del template extrae bajo tu id en vez de un hash del contenido.
¿Prefieres dejar el texto en tu catálogo? Escribe solo su clave: se comprueba y se tipa igual. Mira Claves y catálogos.
Rich text con <Trans>
La misma idea; en Vue cada tag nombrado es una render function que envuelve a sus hijos:
<script setup>
import { Trans } from '@verbaly/vue';
import { h } from 'vue';
const components = { terms: (c) => h('a', { href: '/terms' }, c) };
</script>
<template>
<Trans id='agree' :components='components' />
</template>Para links simples olvídate de la render function: el prop links mapea nombres de tag a hrefs (un string o un objeto href/target/rel). components gana con el mismo nombre; los hrefs javascript: se bloquean.
Los tags permitidos (<em>, <code>…) se renderizan como elementos de verdad, sin necesidad de una render function: la misma lista segura que en HTML plano. richTags la sobrescribe, y la prop instance renderiza sin el plugin.
Nuxt
Las páginas renderizadas en el servidor llegan ya traducidas al idioma del visitante, y el navegador sigue con el mismo idioma y el mismo catálogo, sin flash de texto sin traducir ni diferencias entre servidor y navegador.
- Cada página se renderiza en el idioma del visitante, tomado de la dirección cuando la lleva, y si no de su elección guardada o del header
Accept-Language - Sin flash de texto sin traducir: el HTML que envía el servidor y la página ya hidratada son idénticos, catálogo incluido
- Cada petición tiene su propia instancia, así que dos visitantes simultáneos nunca ven el idioma del otro
- Cero cableado: una sola entrada de módulo reemplaza el setup del plugin de Vite, la negociación y la sincronización de los atributos
langydir
Nuxt necesita el módulo (@verbaly/nuxt) junto al paquete de Vue y el compilador:
pnpm add verbaly @verbaly/nuxt @verbaly/vue pnpm add -D @verbaly/compilerConéctalo
Una línea en nuxt.config. El módulo conecta el plugin de Vite (extracción viva y verbaly/app), elige el idioma por petición y mantiene los atributos lang y dir en sincronía. Si tus direcciones llevan el idioma, las lee él solo y no hay nada más que escribir:
export default defineNuxtConfig({
modules: ['@verbaly/nuxt'],
});
// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them tooDe aquí en adelante es @verbaly/vue normal: useT() / useLocale() y <Trans> funcionan sin cambios en cada componente.
useT() está tipado por tu catálogo: los tipos van a .nuxt/verbaly.d.ts, donde Nuxt los enlaza, y npx verbaly extract escribe ese mismo archivo. Una clave que ningún catálogo tiene hace fallar nuxi typecheck.
Cambiar de idioma
switchLocale de verbaly/app ya conoce tus idiomas y tu modo de URL. Pásale la instancia con la que se pinta esta página: con el idioma en la URL va a la misma página en el otro idioma, y sin él carga el catálogo y cambia la página en su sitio. En los dos casos escribe la cookie que lee el servidor, así que la siguiente petición ya coincide:
<script setup>
import { switchLocale } from 'verbaly/app';
import { useVerbaly } from '@verbaly/vue';
// the instance this page renders with: one per request
const verbaly = useVerbaly();
</script>
<template>
<button @click="switchLocale('es', { instance: verbaly })">Español</button>
</template>- La cookie por defecto es
verbaly-locale(la misma identidad que la clave de storage del core);cookie: falseen las opciones del módulo la desactiva, paraAccept-Languagepuro. fallbackpor defecto es tu idioma fuente; la negociación sigue el orden de preferencia del navegador, yes-PEcoincide cones.ssr: falsetambién está cubierto: el módulo resuelve el idioma en el navegador, leyendo primero la dirección cuando lleva el idioma, luego la cookie, luegonavigator.languages, luego tu fallback.- Sin dependencia de Nuxt en sí: el módulo está tipado estructuralmente, sin
@nuxt/kit. La claveverbalyennuxt.config.tsqueda totalmente tipada (autocompletado y detección de errores de tipeo), y se mantiene compatible con Nuxt 4. - ¿Sitio totalmente estático (
nuxi generate)? Prefiere salida pre-traducida por idioma con verbaly render.