Integrações
Plugin do Vite
O plugin oficial do Vite. Ele extrai os seus textos enquanto você escreve, dá a cada idioma o próprio download e lista o que falta em cada build.
Instalação
Adicione o runtime e este plugin, 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/vite pnpm add -D @verbaly/compilerDepois adicione o plugin à sua config do Vite:
import verbaly from '@verbaly/vite';
export default { plugins: [verbaly()] };As opções são as mesmas da config do CLI: sourceLocale, locales, dir, include, exclude, root. Escreva-as no seu verbaly.config, onde o verbaly check e o verbaly extract também as leem. Uma opção passada ao plugin vence o arquivo, e esses dois comandos nunca a leem, então o build avisa.
Como compila
t`Hola ${name}`virat("x7Ka9q2f", { "name": name }), onde a chave é o hash do conteúdo, estável entre arquivos.- O idioma fonte vai com o seu app. Cada um dos outros é um arquivo próprio, baixado na primeira vez que
setLocale()o pede. - Os catálogos seguem JSON puro: sem formato proprietário, portáveis para qualquer TMS.
- Isso cobre também arquivos
.svelte,.vuee.astro: blocos de script e markup, incluindo a forma de store$tdo Svelte e o frontmatter do Astro. - Um arquivo que importa
@verbaly/react,@verbaly/vueou@verbaly/sveltetambém carregaverbaly/app, entãouseT()encontra a sua instância em um app de página única sem provider acima.
Servidor de dev
- Os textos novos são extraídos enquanto você digita. Catálogos e tipos atualizam um momento depois que você para, e a página recarrega.
- A primeira escrita pega os textos de cada arquivo do seu
include, aberto ou não, como faz oextract. liveExtraction: falseimpede que o servidor de desenvolvimento escreva seus arquivos de tradução: os textos novos continuam aparecendo a partir da memória, como num build, e onpx verbaly extractos escreve quando você decidir.- 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
tcom 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
includeque escrevet`…`, 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 do projeto
verbaly/app é o módulo do seu próprio projeto: o plugin o escreve a partir da sua config e dos seus catálogos, então os seus idiomas, o seu modo de URL e os seus textos de origem já estão nele. Ele também responde a virtual:verbaly, que é o mesmo módulo, exceto com webpack, que lê esse prefixo como um esquema de URL: ali, importe verbaly/app.
Os t e verbaly compartilhados são para o navegador. No servidor, createRequestInstance(locale) constrói uma instância nova por requisição e espera seu catálogo antes de devolver, então a página chega traduzida. createInstance(options) fica para configurações próprias (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. O servidor de desenvolvimento, cada vite build e o que carregar a sua config do Vite, como svelte-check ou Vitest, escrevem os mesmos tipos. Um script que roda o tsc antes do build os escreve primeiro com npx verbaly typegen num clone novo. Mova-os ou desligue-os com a opção dts da config.
O idioma que um visitante escolheu
switchLocale e o useLocale de cada pacote de framework salvam a escolha no navegador, e eles e setLocale definem <html lang> e <html dir>. Um app de página única inicia no idioma fonte, então recupere a escolha antes do primeiro render:
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
// the saved choice, else the browser's, loaded before anything renders
setLocale(resolveLocale({ supported: locales, path: false })).then(render);Um app renderizado no servidor troca de idioma com switchLocale ou useSwitchLocale, que também gravam o cookie que o servidor lê.
Não usa Vite? Use @verbaly/unplugin
@verbaly/unplugin leva o mesmo compilador a webpack 5, Rollup, esbuild e Rspack: o módulo tipado verbaly/app, 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).
Na instalação ele fica no lugar do plugin do Vite:
pnpm add verbaly @verbaly/unplugin pnpm add -D @verbaly/compilerimport { verbaly } from '@verbaly/unplugin';
export default { plugins: [verbaly.webpack()] };
// also: verbaly.rollup() · verbaly.esbuild() · verbaly.rspack()
// languages live in your verbaly.config, where verbaly check reads them tooÉ focado no build: rode npx verbaly extract no seu dev loop ou CI, já que a extração ao vivo e a recarga enquanto você escreve só vêm com o plugin do Vite. Cada build também escreve os tipos, então um clone novo passa no typecheck depois do primeiro build. Só ESM, como o compilador (use webpack.config.mjs).
O módulo do projeto é o mesmo aqui, então a linha de inicialização acima recupera o idioma que um visitante escolheu. Um arquivo que importa @verbaly/react, @verbaly/vue ou @verbaly/svelte também o carrega, então os hooks deles funcionam sem provider no navegador.