REST API
React + i18next
The full API reference will be auto-generated from our OpenAPI 3.1 spec the moment the surface is stable. We'd rather ship a placeholder than fake-doc endpoints that might still move. In the meantime, here's the shape, what it'll cover, and what to do today.
Install
Requires <strong>Node 20 LTS</strong> or newer. Two binaries get installed: <code>verbumia</code> and the shorter alias <code>vrb</code> — interchangeable.
terminal 1npm i @verbumia/react-i18next2. Wrap your app
VerbumiaProvider takes a projectId and an apiKey. Everything else has sane defaults: locale auto-detect from the browser, namespaces lazy-loaded from your CDN, missing-key handler debounced and POSTed automatically.
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); All VerbumiaProvider props
| Prop | Type | Default |
|---|---|---|
| projectId | string | — required |
| apiKey | string | — required |
| 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. Use the hook
useTranslation() returns { t, i18n }. Familiar shape if you've used react-i18next. i18n.ready tells you when initial namespaces have hydrated; i18n.changeLanguage() swaps locale at 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}What you get for free
- Missing-key capture. Any key you call that isn't in the dictionary is queued, debounced (default 5s), and POSTed to your dashboard's missing queue. Production-safe — your fallback still renders.
- CDN-served namespaces. Translation bundles are pulled from
cdn.verbumia.cawith HTTP caching and stale-while-revalidate. No build-time bundling required. - Locale auto-detect. If you don't pass
defaultLocale, the SDK readsnavigator.languageand falls back to your project's default. - Open exports. Whatever you push to Verbumia, you can export back to JSON i18next, XLIFF, or PO. Switch tools tomorrow without rewriting your code.
Custom transport (advanced)
Need to log missing keys to your own observability stack, gate them behind your auth, or stub them out in tests? Pass a transport function. The SDK still debounces and batches; you decide what happens to the 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/>