Saltar al contenido

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:

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

Despué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

main.ts
import { verbalyPlugin } from '@verbaly/vue';
import { verbaly } from 'verbaly/app';

app.use(verbalyPlugin(verbaly));
Inbox.vue
<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>

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:

main.ts
// 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.

Inbox.vue
<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:

Agree.vue
<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.

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

Coné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:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@verbaly/nuxt'],
});

// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them too

De 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:

LangPicker.vue
<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>
↑↓para moverteEnterpara abrir
Copiado en el portapapeles