Referência
API do runtime
O core do verbaly pesa ~3 KB gzip com zero dependências, e tudo se constrói sobre Intl nativo.
createVerbaly(options)
import { createVerbaly } from 'verbaly';
const v = createVerbaly({
locale: 'es',
fallback: ['en'],
messages: { es: { home: { title: 'Inicio' } } },
});| Opção | Tipo | Descrição |
|---|---|---|
| locale | string | Idioma inicial; por padrão navigator.language no navegador |
| fallback | string | string[] | Cadeia de fallback após o narrowing BCP-47 (es-MX → es) |
| messages | object | Idioma → árvore; as chaves aninhadas achatam com pontos (home.title). Uma string vazia conta como não traduzida e segue o fallback, a mesma regra do check |
| loaders | object | Catálogos lazy: idioma → () => import('./es.json'), carregados sob demanda |
| formatters | object | Formatters custom {v:name} |
| onMissing | function | (key, locale): retorne uma string para substituir; silencia o warn-once padrão |
| onResolve | function | (info) em cada t(): key, locale, value e status (hit / fallback / miss). Alimenta os devtools |
Instância
| Membro | Descrição |
|---|---|
| t(key, params?) | Traduz; chaves e params são verificados em tipos a partir das suas mensagens |
| t`...` | Tagged template: interpola texto fonte; o compilador o melhora |
| t.id(key)`...` | Chaves legíveis opt-in: formata o texto inline; o compilador o reescreve para uma chamada com chave |
| setLocale(locale) | Troca o idioma e notifica os assinantes, auto-carrega um catálogo lazy pendente |
| loadLocale(locale) | Carrega um catálogo lazy (narrowing BCP-47, deduplicado): faça await antes de setLocale para trocar sem flash |
| addMessages(locale, tree) | Mescla mensagens em runtime: a primitiva do lazy-loading |
| subscribe(fn) | Listener de mudanças; retorna unsubscribe |
| has(key) | A chave existe na cadeia atual |
| inspect(key) | Locale de origem (from) + texto fonte de uma key (devtools/ferramentas). O campo foi renomeado de locale em 0.17.0 (breaking) para alinhar com ResolveInfo.from |
| locale | Idioma atual (readonly) |
| locales | Idiomas carregados + carregáveis (readonly): alimenta um switcher a partir de uma única fonte de verdade |
| version | Contador de mudanças que impulsiona os adapters de frameworks |
Helpers de idioma
import { negotiateLocale, persistLocale, resolveLocale, resolveRequestLocale, switchLocale } from 'verbaly';
resolveLocale({ supported: ['en', 'es', 'pt'] }); // storage → navigator → fallback
persistLocale('es'); // localStorage + <html lang>
// server-side (0.16.0): match an Accept-Language header
negotiateLocale('es-PE,en;q=0.8', ['en', 'es']); // → 'es'
// per-request (0.17.0): cookie value → header → fallback
resolveRequestLocale({ supported: ['en', 'es'], cookie, header });
// client switch for SSR setups (0.18.0): catalog → locale → cookie + <html lang>
await switchLocale(instance, 'es');resolveLocale escolhe o idioma inicial (escolha salva, depois navigator.languages com narrowing BCP-47, depois fallback); persistLocale lembra uma troca. Ambos são SSR-safe e aceitam um storageKey custom (false desativa o storage). Ver HTML puro → Bootstrap de idioma para o padrão completo.
negotiateLocale(header, supported, fallback?) (0.16.0) é a contraparte do lado do servidor: entregue a ela um header Accept-Language e seus locales e ela devolve a melhor correspondência (respeita os q-values, es-PE corresponde a es, sem diferenciar maiúsculas). Funciona com qualquer servidor; as integrações do SvelteKit, do Nuxt e do Next.js a usam por baixo.
resolveRequestLocale(options) (0.17.0) toma a decisão inteira por request em uma só chamada: primeiro o valor de um cookie salvo, depois o header Accept-Language, depois seu fallback. LOCALE_STORAGE_KEY exporta o nome compartilhado (verbaly-locale) usado pelo storage do browser e pelo cookie SSR.
switchLocale(instance, locale, options?) (0.18.0) é a troca de idioma do lado do cliente compartilhada pelas integrações SSR: carrega o catálogo primeiro, depois troca o locale, grava o cookie verbaly-locale e atualiza o atributo lang. É seguro chamá-la no servidor (lá ela não faz nada); o @verbaly/sveltekit a re-exporta.
Segurança em nível de tipos
v.t('home.title'); ✓
v.t('home.title', { x: 1 }); ✗ no params declared
v.t('nope'); ✗ unknown keyO TypeScript parseia suas mensagens: FlatKeys achata árvores aninhadas, ParamNames lê as ocorrências de {param}, e TArgs exige os params exatamente quando a mensagem os declara.
Exports de baixo nível
Construindo ferramentas sobre o Verbaly? O pacote também exporta parse(message) (o AST da mensagem), flatten(tree) (árvore aninhada → dot-keys), safeHref(href) (o guardião de esquemas inseguros por trás dos named links) e, desde 0.17.0, normalizeLink(link), o normalizador de links único que todos os adapters compartilham, mais o tipo RichLink. São as mesmas peças que o compilador usa.