Guias
No servidor
O core roda onde o JavaScript rodar, incluindo Node. Crie uma instância, passe o locale, chame t(). Sem DOM.
Uma instância por request
Construa uma instância nova por request e entregue a ela o locale do visitante. negotiateLocale lê o header Accept-Language e escolhe a melhor correspondência entre seus locales (entende os q-values, e es-PE corresponde a es). resolveRequestLocale toma a decisão inteira em uma chamada: primeiro o endereço quando ele leva o idioma, depois a escolha salva, depois o navegador, depois seu fallback. Instâncias não compartilham estado, então dois requests nunca misturam seus idiomas.
import { createVerbaly, negotiateLocale } from 'verbaly';
import es from './locales/es.json';
import en from './locales/en.json';
function handle(req) {
const locale = negotiateLocale(req.headers['accept-language'], ['en', 'es']);
const v = createVerbaly({ locale, fallback: 'en', messages: { en, es } });
return v.t('home.title');
}Quando seus endereços levam o idioma
Se suas páginas ficam em /es/dashboard, esse endereço é a resposta. Quem abrir o link recebe espanhol, tendo escolhido um idioma aqui ou não, porque um endereço é público e se compartilha enquanto uma escolha salva é de uma pessoa só. Uma página sem prefixo passa a significar seu idioma de origem, então quem escolheu espanhol uma vez não vê suas páginas em inglês traduzidas por acidente.
Você ativa isso contando à sua integração o routing que já configurou. É só isso, por stack:
| Stack | O que você escreve |
|---|---|
| SvelteKit | Passe routing para verbalyHandle, e adicione verbalyReroute em hooks.ts para que uma única árvore de rotas sirva todos os idiomas |
| Nuxt | Nada: o módulo lê o endereço por você |
| Next.js | routing: 'prefix-all' na sua config, e setRequestLocale(locale) no seu layout [locale], antes que qualquer coisa peça texto |
| Astro | createRequestInstance(Astro.currentLocale ?? sourceLocale) na página |
Suas páginas também podem apontar umas para as outras nos buscadores. alternateLinks te dá a lista de endereços de uma página em todos os idiomas, a mesma lista que um site renderizado estaticamente recebe, então uma página renderizada no servidor não é de segunda classe. Veja Estratégia de URL.
Renderize o HTML de antemão
Para sites estáticos, verbaly render pré-preenche seu HTML compilado por idioma para que as páginas cheguem já traduzidas. Veja CLI → Renderização estática.
Meta-frameworks
Em SvelteKit, Nuxt e Next.js você não liga nada disto à mão. A integração do SvelteKit, o módulo do Nuxt e a integração do Next.js escolhem o idioma por requisição e hidratam sem piscar, tudo sobre estas mesmas primitivas.