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:
- Traduza com composables (useT, useLocale) que reagem a cada troca de idioma
- Vincule o idioma direto a um select:
useLocale()retorna um computed gravável - Mantenha chaves e params totalmente tipados, com autocompletar das suas próprias mensagens
- Zero vazamentos: as assinaturas são por componente e limpas via
onScopeDispose
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/compilerDepois 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
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>- As assinaturas são por componente e limpas ao desmontar via
onScopeDispose. useLocale()retorna um computed gravável, então vincule-o direto a um select.- Sem o plugin instalado, no navegador?
useT()euseLocale()leem a instância que overbaly/appcria, e o plugin do bundler carrega esse módulo em cada arquivo que importa@verbaly/vue, então um app de página única ou um teste de componente não precisa de preparação. No servidor o plugin é obrigatório, porque cada requisição tem a sua própria instância.
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:
// 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.
<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:
<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.
- Cada página renderiza no idioma do visitante, tirado do endereço quando ele o leva, e se não da escolha salva ou do header
Accept-Language - Sem flash de texto sem tradução: o HTML que o servidor envia e a página já hidratada são idênticos, catálogo incluído
- Cada requisição tem sua própria instância, então dois visitantes simultâneos nunca veem o idioma um do outro
- Zero fiação: uma única entrada de módulo substitui o setup do plugin do Vite, a negociação e a sincronização dos atributos
langedir
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/compilerConecte 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:
export default defineNuxtConfig({
modules: ['@verbaly/nuxt'],
});
// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them tooDaqui 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:
<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>- O cookie padrão é
verbaly-locale(a mesma identidade da chave de storage do core);cookie: falsenas opções do módulo o desativa, paraAccept-Languagepuro. fallbacké por padrão seu idioma fonte; a negociação segue a ordem de preferência do navegador, ees-PEcorresponde aes.ssr: falsetambém está coberto: o módulo resolve o idioma no navegador, lendo primeiro o endereço quando ele leva o idioma, depois o cookie, depoisnavigator.languages, depois seu fallback.- Sem dependência do próprio Nuxt: o módulo é tipado estruturalmente, sem
@nuxt/kit. A chaveverbalyemnuxt.config.tsfica totalmente tipada (autocompletar e detecção de erros de digitação), e continua compatível com o Nuxt 4. - Site totalmente estático (
nuxi generate)? Prefira saída pré-traduzida por idioma com verbaly render.