Integrações
Svelte
O pacote oficial de Svelte 5 para Verbaly. Stores idiomáticos sobre o mesmo core reativo, factories de stores para uso no nível do app, e um componente <Trans> para rich text.
O que você pode fazer:
- Traduza com stores:
$tre-renderiza a cada troca de idioma, sem fiação - Vincule um seletor de idioma em uma linha:
bind:valueno store do idioma simplesmente funciona - Use contexto ou factories de stores, com ou sem árvore de componentes
- Mapeie uma tag de uma mensagem para seu próprio componente com a prop components do <Trans>
Instalação
Adicione o runtime, este pacote e o plugin do Vite, 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/svelte @verbaly/vite pnpm add -D @verbaly/compilerDepois adicione verbaly() aos plugins do vite.config. Ele escreve verbaly/app, o módulo que os seus componentes leem.
Setup e stores
<script>
// root component / layout:
import { provideVerbaly } from '@verbaly/svelte';
import { verbaly } from 'verbaly/app';
provideVerbaly(verbaly);
</script>
<script>
// any child component:
import { useT, useLocale } from '@verbaly/svelte';
const t = useT();
const locale = useLocale(); // writable store
const count = 3;
</script>
<p>{$t`You have ${count} messages`}</p>
<select bind:value={$locale}>…</select>- Stores idiomáticos:
$tre-renderiza a cada troca de idioma;bind:value={$locale}num select funciona direto. - Sem árvore de componentes?
tStore(instance)/localeStore(instance)constroem os mesmos stores sem context, compartilhados por todo o app. - Sem
provideVerbalyacima de um componente, no navegador?useT()lê a instância que overbaly/appcria, e o plugin do bundler carrega esse módulo em cada componente que importa@verbaly/svelte, então um app de página única ou um teste de componente não precisa de wrapper. No servidor um componente pai tem de fornecê-la, porque cada requisição tem a sua própria instância.
O idioma que um visitante escolhe
Definir $locale troca todos os componentes, e a página acompanha: <html lang>, <html dir> e a escolha, salva no navegador. Um app de página única inicia no idioma fonte, então recupere essa escolha antes de montar:
// the saved choice, else the browser's, loaded before anything renders
import { mount } from 'svelte';
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';
import App from './App.svelte';
setLocale(resolveLocale({ supported: locales, path: false })).then(() =>
mount(App, { target: document.getElementById('app')! }),
);Onde um servidor renderiza a página, como no SvelteKit, troque de idioma com switchLocale de verbaly/app: ele também grava o cookie que o servidor lê.
Escreva o texto no lugar
O compilador também lê seus arquivos .svelte: escreva o texto fonte com o tag do store, em uma expressão do markup ou no script, e ele é extraído, ganha sua chave e seus tipos ao salvar. O texto que só é exibido nunca é extraído, então uma página pode mostrar t`…` como exemplo sem risco. Sem inventar chaves, sem tocar em catálogos.
<h1>{$t`Hola ${name}, tienes ${count} mensajes`}</h1>
<!-- extracted on save; the build rewrites it to: -->
<h1>{$t('oHfbnDd4', { name, count })}</h1>Prefere chaves legíveis? $t.id('inbox.title') antes do template extrai sob o seu id em vez de um hash do conteúdo.
Prefere deixar o texto no seu catálogo? Escreva só a chave dele: ela é verificada e tipada do mesmo jeito. Veja Chaves e catálogos.
Rich text com <Trans>
O Svelte tem o próprio componente: importe do subpath Trans.svelte (componente cru, compilado pelo seu bundler):
<script>
import Trans from '@verbaly/svelte/Trans.svelte';
import DocsLink from './DocsLink.svelte';
</script>
<Trans id='home.title' />
<Trans id='greet' values={{ name: 'Aron' }} />
<!-- message: 'Read the <docs>guide</docs>' → your component wraps the tag content -->
<Trans id='cta' components={{ docs: DocsLink }} />- Tags da mensagem (
The <em>build</em> gate) renderizam como elementos reais com a mesma lista de tags permitidas dodata-verbaly-rich. Tags desconhecidas se desfazem em texto inerte,richTagssobrescreve. - Usa a instância do
provideVerbaly; passeinstance={verbaly}explícito quando não há contexto. Re-renderiza a cada troca de idioma. - Links nomeados: a prop
linksrenderiza tags nomeadas como elementos<a>reais, com hrefs do seu código, nunca das mensagens;javascript:bloqueado. - Seus próprios componentes: a prop
componentsmapeia uma tag para um componente Svelte que recebe o conteúdo da tag como children, e vence links e tags permitidas.
SvelteKit
As páginas renderizadas no servidor chegam já traduzidas no idioma do visitante, e o navegador continua com o mesmo idioma e o mesmo catálogo, sem flash de texto sem tradução nem diferenças entre servidor e navegador.
- Cada página renderiza no idioma do visitante, tirado do endereço quando ele o leva, e se não da escolha salva ou do header
Accept-Language - Sem flash de texto sem tradução: o HTML que o servidor envia e a página já hidratada são idênticos, catálogo incluído
- Cada requisição tem sua própria instância, então dois visitantes simultâneos nunca veem o idioma um do outro
- Um seletor de idioma em uma chamada:
switchLocalecarrega o catálogo e persiste a escolha para o próximo render do servidor
O SvelteKit precisa do pacote de servidor (@verbaly/sveltekit) junto ao pacote do Svelte, ao plugin do Vite e ao compilador:
pnpm add verbaly @verbaly/sveltekit @verbaly/svelte @verbaly/vite pnpm add -D @verbaly/compilerO init escreve verbaly.config.ts e o seu catálogo fonte. Liste ali os seus idiomas (locales: ['en', 'es']): o build, o verbaly extract e o verbaly check os leem.
Conecte tudo
Três fios no servidor, um no cliente. Primeiro o plugin do Vite e o placeholder de lang:
// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import verbaly from '@verbaly/vite';
export default { plugins: [verbaly(), sveltekit()] };
<!-- src/app.html -->
<html lang="%verbaly.lang%" dir="%verbaly.dir%">O hook de servidor resolve o idioma por requisição e preenche o placeholder. Passe routing e o endereço decide quando ele leva o idioma, caindo para a escolha salva, depois Accept-Language, depois seu fallback:
// src/hooks.server.ts
import { verbalyHandle } from '@verbaly/sveltekit';
import { locales, routing } from 'verbaly/app';
export const handle = verbalyHandle({ locales, routing });
// src/app.d.ts
declare namespace App {
interface Locals { verbalyLocale: string }
}Entregue o idioma ao cliente e construa uma instância por render com o catálogo aguardado, a garantia sem flash:
// +layout.server.ts
export const load = ({ locals }) => ({ locale: locals.verbalyLocale });
// +layout.ts
import { createRequestInstance } from 'verbaly/app';
export const load = async ({ data }) => ({
...data,
verbaly: await createRequestInstance(data.locale), // catalog ready BEFORE render
});
<!-- +layout.svelte -->
<script>
import { provideVerbaly } from '@verbaly/svelte';
let { data, children } = $props();
provideVerbaly(data.verbaly);
</script>
{@render children()}Daqui em diante é @verbaly/svelte normal: os stores useT() / useLocale() e o Trans.svelte funcionam sem mudanças em cada componente.
$t é tipado pelo seu catálogo: os tipos vão para src/verbaly.d.ts, a pasta que o tsconfig do SvelteKit lê, então o svelte-check os vê sem configurar nada e falha com uma chave que nenhum catálogo tem.
Uma única árvore de rotas para todos os idiomas
Se suas páginas ficam em /es/docs, você não precisa de uma pasta de rotas por idioma. Um único hook universal faz /es/docs renderizar pela sua rota /docs, então suas rotas ficam exatamente como estavam:
import { verbalyReroute } from '@verbaly/sveltekit';
import { locales } from 'verbaly/app';
export const reroute = verbalyReroute({ locales });Fica em hooks.ts e não em hooks.server.ts, porque navegar entre páginas no navegador precisa resolver do mesmo jeito que o servidor resolveu.
Trocar de idioma
O switchLocale de verbaly/app já conhece os seus idiomas e o seu modo de URL. Passe a ele a instância com que esta página é renderizada: com o idioma na URL ele vai para a mesma página no outro idioma, e sem ele carrega o catálogo e troca a página no lugar. Nos dois casos ele grava o cookie que o hook do servidor lê, então a próxima requisição já bate:
<script>
import { switchLocale } from 'verbaly/app';
import { useVerbaly } from '@verbaly/svelte';
// the instance this page renders with: one per request
const verbaly = useVerbaly();
</script>
<button onclick={() => switchLocale('es', { instance: verbaly })}>Español</button>- O cookie padrão é
verbaly-locale(a mesma identidade da chave de storage do core);cookie: falseem qualquer um dos lados o desativa, paraAccept-Languagepuro. fallbacké por padrão seu primeiro idioma; a negociação segue a ordem de preferência do navegador, ees-PEcorresponde aes.- Sem dependência do próprio SvelteKit: o hook é tipado estruturalmente e continua compatível com o SvelteKit 2 e 3.