Ir para o conteúdo

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.

  • Node 22.12+ · Vite 7/8
  • TypeScript-first
  • ~3 KB0 dependências

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.

  1. 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/vite
     pnpm add -D @verbaly/compiler

    O runtime é sempre o mesmo; o plugin depende do seu setup. Em webpack, Rollup, esbuild ou Rspack você instala @verbaly/unplugin no lugar, e Next.js, Nuxt e Astro têm o seu. Ver Pacotes.

  2. Gere tudo com um comando

    npx verbaly init escreve 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 --source e aqueles para os quais traduz com --locales. Nunca sobrescreve nada. Ligar o plugin é com você, e é o passo seguinte.

    npx verbaly init --source es --locales pt   # config + locales/es.json + locales/pt.json
  3. Adicione o plugin

    vite.config.ts
    import verbaly from '@verbaly/vite';
    
    export default {
      plugins: [verbaly()],
    };

    As suas opções ficam no verbaly.config que o init escreveu, onde o build e o verbaly check as leem:

    verbaly.config.ts
    import type { VerbalyConfig } from '@verbaly/compiler';
    
    export default {
      sourceLocale: 'es',
      locales: ['pt'],
    } satisfies VerbalyConfig;

    sourceLocale é o idioma em que você escreve e locales, 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 rode npx verbaly extract. Se deixar locales de fora, cada catálogo JSON em locales/ conta como idioma, mesmo um arquivo vazio que você acabou de criar.

  4. Escreva texto, não chaves

    src/main.ts
    import { 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 again

    Em 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.

  5. Traduza e verifique

    extract preenche os seus catálogos: o seu idioma fonte fica pronto e cada um dos outros espera com um texto vazio. Por isso o check falha aqui, e diz o que falta.

    npx verbaly extract   # sync catalogs + types
    npx verbaly check     # exit 1 if anything is missing

    Escreva a tradução em locales/pt.json. A chave é a que o extract escreveu, e os espaços como {name} ficam como estão:

    locales/pt.json
    {
      "oHfbnDd4": "Olá {name}, você tem {count} mensagens"
    }

    Agora o npx verbaly check passa. Rode npx vite e a página mostra Olá Ana, você tem 3 mensagens. npx verbaly translate pode preencher um catálogo para você, como rascunhos que uma pessoa revisa.

O que o módulo do projeto exporta

ExportDescrição
tTraduz: 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
verbalyA instância subjacente (uso avançado)
↑↓para navegarEnterpara abrir
Copiado para a área de transferência