Ir para o conteúdo

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:

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

Depois adicione verbaly() aos plugins do vite.config. Ele escreve verbaly/app, o módulo que os seus componentes leem.

Setup e stores

+layout.svelte · Inbox.svelte
<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>

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:

main.ts
// 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.

Inbox.svelte
<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):

Title.svelte
<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 }} />

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.

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

O 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 · src/app.html
// 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 · src/app.d.ts
// 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:

src/routes/+layout.server.ts · +layout.ts · +layout.svelte
// +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:

src/hooks.ts
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:

LangPicker.svelte
<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>
↑↓para navegarEnterpara abrir
Copiado para a área de transferência