Início
Primeiros passos
O Verbaly inverte o fluxo i18n habitual: você escreve texto natural no seu código e o compilador extrai as mensagens, gera chaves estáveis, tipos e bundles por idioma. Requisitos: Node 22.12+ e Vite 7 ou 8.
Estes passos são para um projeto Vite em TypeScript puro, o caminho mais curto para ver funcionar. Em outra configuração a ideia é a mesma, e a página dela tem as linhas exatas: React e Next.js, Vue e Nuxt, Svelte e SvelteKit, Astro ou HTML puro.
Instalação
Adicione o runtime e o plugin do Vite, e depois o compilador, que é onde vive o comando
verbaly. Escolha seu gerenciador de pacotes.pnpm add verbaly @verbaly/vitepnpm add -D @verbaly/compilerO runtime é sempre o mesmo; o plugin depende do seu setup. Em webpack, Rollup, esbuild ou Rspack você instala
@verbaly/unpluginno lugar, e Next.js, Nuxt e Astro têm o seu. Ver Pacotes.Gere tudo com um comando
npx verbaly initescreve a config e um catálogo por idioma, e diz de quais pacotes o seu projeto precisa: o plugin e, com Vite ou outro bundler, o de React, Vue ou Svelte se o seu app usar um. Informe o idioma em que você escreve com--sourcee aqueles para os quais traduz com--locales. Nunca sobrescreve nada. Ligar o plugin é com você, e é o passo seguinte.Adicione o plugin
vite.config.tsimport verbaly from '@verbaly/vite'; export default { plugins: [verbaly()], };As suas opções ficam no
verbaly.configque oinitescreveu, onde o build e overbaly checkas leem:verbaly.config.tsimport type { VerbalyConfig } from '@verbaly/compiler'; export default { sourceLocale: 'es', locales: ['pt'], } satisfies VerbalyConfig;sourceLocaleé o idioma em que você escreve elocales, aqueles para os quais traduz. Essa lista é a lista inteira, então um arquivo que ficou esquecido é ignorado. Para adicionar um idioma depois, coloque-o ali e rodenpx verbaly extract. Se deixarlocalesde fora, cada catálogo JSON emlocales/conta como idioma, mesmo um arquivo vazio que você acabou de criar.Escreva texto, não chaves
src/main.tsimport { t, setLocale } from 'verbaly/app'; const name = 'Ana'; const count = 3; const app = document.querySelector('#app')!; const paint = () => { app.textContent = t`Hola ${name}, tienes ${count} mensajes`; }; paint(); setLocale('pt').then(paint); // loads its catalog, then paints againEm dev, o plugin extrai as mensagens ao vivo: seu catálogo fonte se preenche sozinho, os outros idiomas recebem placeholders
"", e os tipos gerados mantêm chaves e params tipados.Traduza e verifique
extractpreenche os seus catálogos: o seu idioma fonte fica pronto e cada um dos outros espera com um texto vazio. Por isso ocheckfalha aqui, e diz o que falta.Escreva a tradução em
locales/pt.json. A chave é a que oextractescreveu, e os espaços como{name}ficam como estão:locales/pt.json{ "oHfbnDd4": "Olá {name}, você tem {count} mensagens" }Agora o
npx verbaly checkpassa. Rodenpx vitee a página mostra Olá Ana, você tem 3 mensagens.npx verbaly translatepode preencher um catálogo para você, como rascunhos que uma pessoa revisa.
O que o módulo do projeto exporta
| Export | Descrição |
|---|---|
| t | Traduz: t('key', params) ou o tagged t`...` |
| setLocale(locale) | Carrega esse idioma e então troca. Retorna uma promise, então você pode esperar por ela |
| getLocale() | Idioma atual |
| subscribe(fn) | Re-executa a UI em mudanças de idioma/mensagens; retorna unsubscribe |
| verbaly | A instância subjacente (uso avançado) |