Plugin do Vite

import verbaly from '@verbaly/vite';

export default { plugins: [verbaly({ sourceLocale: 'es' })] };

As opções são as mesmas da config do CLI: sourceLocale, locales, dir, include, exclude, root. As opções inline vencem o arquivo de config.

Como compila

• t`Hola ${name}` vira t("x7Ka9q2f", { "name": name }), onde a chave é o hash do conteúdo, estável entre arquivos.
• O idioma fonte vai inline; cada outro idioma vira seu próprio chunk lazy, carregado no primeiro setLocale().
• Os catálogos seguem JSON puro: sem formato proprietário, portáveis para qualquer TMS.
• Isso cobre também arquivos .svelte, .vue e .astro: blocos de script e markup, incluindo a forma de store $t do Svelte e o frontmatter do Astro.

Servidor de dev

• Os textos novos são extraídos enquanto você digita; catálogos e tipos atualizam com debounce, e o servidor dispara um reload completo.
• Editar um catálogo à mão o recarrega. Um texto que é do seu código volta ao lugar, e o terminal aponta o arquivo e a linha onde ele vive. Toda escrita parte dos arquivos em disco, então um checkout nunca é desfeito com um texto anterior, e um catálogo salvo pela metade é reportado numa linha enquanto o servidor continua rodando.
• O terminal nomeia cada uma destas coisas uma vez: uma chave escrita com dois textos, um t com outro nome, uma tradução mais velha que o seu texto fonte.
• Quando o servidor de desenvolvimento ou o build começa, ele aponta uma vez cada arquivo fora do seu include que escreve t`…`, com o padrão a adicionar: esse texto nunca é extraído, então apareceria no seu idioma fonte em todo lugar.

Build

O módulo virtual

import { t, verbaly, setLocale, getLocale, subscribe } from 'virtual:verbaly';

// SSR: request-scoped instances + locale metadata
import { createRequestInstance, createInstance, loadMessages, locales, sourceLocale } from 'virtual:verbaly';

// fresh instance, catalog awaited, no flash. One call per request:
const v = await createRequestInstance(locale);

// raw catalog for a locale (SSR integrations serialize it to the client):
const messages = await loadMessages(locale);

// client-side routing over pre-translated pages (render.inlineCatalog):
import { adoptPage } from 'virtual:verbaly';
adoptPage({ root: nextDocument, path: nextUrl.pathname });

O singleton t/verbaly é para o browser. No servidor, createRequestInstance(locale) constrói uma instância nova por request e espera seu catálogo antes de devolver: o contrato no-FOUC em uma chamada. createInstance(options) fica para setups custom (veja Server-side).

adoptPage existe quando render.inlineCatalog está ligado. Cada página leva apenas as mensagens que mostra, por isso um router que troca de documento tem de entregar as da seguinte: chame-o a partir do hook que dispara antes da troca. O <ClientRouter /> do Astro já vem ligado.

Os tipos gerados ficam em src/verbaly.d.ts (a raiz quando não há src/), a pasta que o tsconfig dos templates do Vite e do SvelteKit já lê, e tipam este módulo: as chaves autocompletam e os params de cada chave são exigidos. Um clone novo os escreve com npx verbaly typegen antes do tsc. Mova-os ou desligue-os com a opção dts da config.

Não usa Vite? Use @verbaly/unplugin

@verbaly/unplugin leva o mesmo compilador a webpack 5, Rollup, esbuild e Rspack: o módulo tipado virtual:verbaly, a transformação dos templates marcados e o relatório do build, que diz cada problema uma vez mesmo quando um watch recompila (failOnMissing: true para o build em vez disso).

import { verbaly } from '@verbaly/unplugin';

export default { plugins: [verbaly.webpack({ locales: ['en', 'es'] })] };
// also: verbaly.rollup(…) · verbaly.esbuild(…) · verbaly.rspack(…)

É focado no build: rode npx verbaly extract no seu dev loop ou CI, já que a extração ao vivo e o HMR continuam sendo o valor deste plugin do Vite. Só ESM, como o compilador (use webpack.config.mjs).