API REST
React + i18next
A referência API completa será auto-gerada a partir da nossa spec OpenAPI 3.1 assim que a superfície for estável. Preferimos shipar um placeholder do que fake-doc de endpoints que ainda podem mexer-se. Entretanto, aqui está a forma, o que vai cobrir e o que fazer hoje.
Instalar
Requer <strong>Node 20 LTS</strong> ou mais recente. São instalados dois binários: <code>verbumia</code> e o alias mais curto <code>vrb</code> — permutáveis.
terminal 1npm i @verbumia/react-i18next2. Envolve a tua app
VerbumiaProvider recebe um projectId e uma apiKey. Tudo o resto tem defaults sensatos: deteção automática do locale a partir do browser, namespaces carregados a pedido a partir do teu CDN, handler de chaves em falta com debounce e POST automático.
main.tsx 1// src/main.tsx2import { VerbumiaProvider } from "@verbumia/react-i18next";3import { createRoot } from "react-dom/client";4import { App } from "./App"; 6createRoot(document.getElementById("root")!).render(7 <VerbumiaProvider8 projectId="proj_xxx"9 apiKey={import.meta.env.VITE_VERBUMIA_KEY}10 defaultLocale="en"11 namespaces={["common"]}12 >13 <App />14 </VerbumiaProvider>15); Todas as props do VerbumiaProvider
| Prop | Type | Default |
|---|---|---|
| projectId | string | — obrigatória |
| apiKey | string | — obrigatória |
| defaultLocale | string | browser |
| defaultNS | string | "common" |
| namespaces | string[] | ["common"] |
| cdnUrl | string | cdn.verbumia.ca |
| baseUrl | string | api.verbumia.ca |
| missingHandlerEndpoint | string | /v1/missing |
| debounceMs | number | 5000 |
| transport | (batch) => void | Promise<void> | internal |
3. Usa o hook
useTranslation() devolve { t, i18n }. Forma familiar se já usaste react-i18next. i18n.ready indica quando os namespaces iniciais estão hidratados; i18n.changeLanguage() troca o locale em runtime.
Checkout.tsx 1// src/Checkout.tsx2import { useTranslation } from "@verbumia/react-i18next"; 4export function Checkout() {5 const { t, i18n } = useTranslation("common"); 7 if (!i18n.ready) return null; // first paint after hydration 9 return (10 <button onClick={() => i18n.changeLanguage("fr")}>11 {t("checkout.review.confirm")}12 </button>13 );14}O que recebes de borla
- Captura de chaves em falta. Qualquer chave que chamares e que não esteja no dicionário é enfileirada, com debounce (5s por defeito) e enviada por POST para a fila de chaves em falta do teu dashboard. Seguro em produção — o teu fallback continua a renderizar.
- Namespaces servidos por CDN. Os bundles de tradução são puxados de
cdn.verbumia.cacom caching HTTP e stale-while-revalidate. Sem necessidade de bundling em build-time. - Deteção automática do locale. Se não passares
defaultLocale, o SDK lênavigator.languagee recai no default do teu projeto. - Exports abertos. O que enviares para o Verbumia, podes exportar de volta para JSON i18next, XLIFF ou PO. Muda de ferramenta amanhã sem reescrever código.
Transport personalizado (avançado)
Precisas de registar chaves em falta na tua própria stack de observability, escondê-las atrás da tua auth ou simulá-las em testes? Passa uma função transport. O SDK continua a fazer debounce e batching; tu decides o que acontece ao batch.
main.tsx 1// custom transport — useful for tests, edge cases, or auditing2<VerbumiaProvider3 projectId="proj_xxx"4 apiKey={import.meta.env.VITE_VERBUMIA_KEY}5 debounceMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>