Ir para o conteúdo

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/compiler
npx verbaly init

Depois adicione o plugin à sua config do Vite:

vite.config.ts
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

Servidor de dev

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.

import { t, verbaly, setLocale, getLocale, subscribe } from 'verbaly/app';

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

// 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 'verbaly/app';
adoptPage({ root: nextDocument, path: nextUrl.pathname });

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:

main.ts
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/compiler
npx verbaly init
webpack.config.mjs
import { 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.

↑↓para navegarEnterpara abrir
Copiado para a área de transferência