Ir para o conteúdo

Integrações

Vue

O pacote oficial de Vue 3 para Verbaly. Composables com limpeza automática, um componente <Trans> para rich text, e chaves + params totalmente tipados.

O que você pode fazer:

Instalação

Adicione o runtime, este pacote e o plugin do Vite, e depois o compilador, que é onde vive o comando verbaly. O init escreve a sua config e o seu catálogo fonte.

 pnpm add verbaly @verbaly/vue @verbaly/vite
 pnpm add -D @verbaly/compiler
npx verbaly init

Depois adicione verbaly() aos plugins do vite.config. Ele escreve verbaly/app, o módulo que os seus componentes leem.

Em webpack, Rollup, esbuild ou Rspack, instale @verbaly/unplugin no lugar de @verbaly/vite: outros bundlers mostra como.

Setup e 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>

O idioma que um visitante escolhe

Escrever locale.value troca todos os componentes, e a página acompanha: <html lang>, <html dir> e a escolha, salva no navegador. Um app de página única inicia no idioma fonte, então recupere essa escolha 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'));

Onde um servidor renderiza a página, como no Nuxt, troque de idioma com switchLocale de verbaly/app: ele também grava o cookie que o servidor lê.

Escreva o texto no lugar

O compilador também lê seus arquivos .vue: escreva o texto fonte em uma interpolação, em um binding de diretiva ou no script setup, e ele é extraído, ganha sua chave e seus tipos ao salvar. O texto que só é exibido nunca é extraído, então uma página pode mostrar t`…` como exemplo sem risco. Sem inventar chaves, sem tocar em 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', …) -->

Prefere chaves legíveis? t.id('inbox.title') antes do template extrai sob o seu id em vez de um hash do conteúdo.

Prefere deixar o texto no seu catálogo? Escreva só a chave dele: ela é verificada e tipada do mesmo jeito. Veja Chaves e catálogos.

Rich text com <Trans>

A mesma ideia; no Vue cada tag nomeado é uma render function que envolve seus filhos:

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 dispense a render function: a prop links mapeia nomes de tag para hrefs (uma string ou um objeto href/target/rel). components ganha no mesmo nome; hrefs javascript: são bloqueados.

As tags permitidas (<em>, <code>…) renderizam como elementos de verdade, sem precisar de uma render function: a mesma lista segura do HTML puro. richTags a sobrescreve, e a prop instance renderiza sem o plugin.

Nuxt

As páginas renderizadas no servidor chegam já traduzidas no idioma do visitante, e o navegador continua com o mesmo idioma e o mesmo catálogo, sem flash de texto sem tradução nem diferenças entre servidor e navegador.

O Nuxt precisa do módulo (@verbaly/nuxt) junto ao pacote do Vue e ao compilador:

 pnpm add verbaly @verbaly/nuxt @verbaly/vue
 pnpm add -D @verbaly/compiler
npx verbaly init

Conecte tudo

Uma linha no nuxt.config. O módulo liga o plugin do Vite (extração viva e verbaly/app), escolhe o idioma por requisição e mantém os atributos lang e dir em sincronia. Se seus endereços levam o idioma, ele os lê sozinho e não há nada a mais para escrever:

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

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

Daqui em diante é @verbaly/vue normal: useT() / useLocale() e o <Trans> funcionam sem mudanças em cada componente.

useT() é tipado pelo seu catálogo: os tipos vão para .nuxt/verbaly.d.ts, onde o Nuxt os vincula, e npx verbaly extract escreve esse mesmo arquivo. Uma chave que nenhum catálogo tem faz o nuxi typecheck falhar.

Trocar de idioma

O switchLocale de verbaly/app já conhece os seus idiomas e o seu modo de URL. Passe a ele a instância com que esta página é renderizada: com o idioma na URL ele vai para a mesma página no outro idioma, e sem ele carrega o catálogo e troca a página no lugar. Nos dois casos ele grava o cookie que o servidor lê, então a próxima requisição já bate:

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 navegarEnterpara abrir
Copiado para a área de transferência