API REST
React + i18next
La référence API complète sera auto-générée à partir de notre spec OpenAPI 3.1 dès que la surface sera stable. On préfère shipper un placeholder plutôt que de fake-doc des endpoints qui peuvent encore bouger. En attendant, voici la forme, ce que ça couvrira, et quoi utiliser aujourd'hui.
Installer
Requiert <strong>Node 20 LTS</strong> ou plus récent. Deux binaires sont installés : <code>verbumia</code> et l'alias plus court <code>vrb</code> — interchangeables.
terminal 1npm i @verbumia/react-i18next2. Envelopper votre app
VerbumiaProvider prend un projectId et un apiKey. Tout le reste a des défauts raisonnables : détection auto de la locale depuis le navigateur, namespaces chargés à la demande depuis votre CDN, handler de clés manquantes debouncé et POST automatique.
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); Toutes les props de VerbumiaProvider
| Prop | Type | Défaut |
|---|---|---|
| projectId | string | — obligatoire |
| apiKey | string | — obligatoire |
| 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. Utiliser le hook
useTranslation() retourne { t, i18n }. Forme familière si vous avez utilisé react-i18next. i18n.ready indique quand les namespaces initiaux sont hydratés ; i18n.changeLanguage() change la locale à l'exécution.
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}Ce que vous obtenez gratuitement
- Capture des clés manquantes. Toute clé que vous appelez sans qu'elle soit au dictionnaire est mise en file, debouncée (5s par défaut), et POST vers la file de votre dashboard. Sans risque en prod — votre fallback continue de s'afficher.
- Namespaces servis depuis le CDN. Les bundles de traduction sont tirés de
cdn.verbumia.caavec cache HTTP et stale-while-revalidate. Aucun bundling au build requis. - Détection auto de la locale. Si vous ne passez pas
defaultLocale, le SDK litnavigator.languageet retombe sur la valeur par défaut de votre projet. - Exports ouverts. Tout ce que vous pushez dans Verbumia, vous pouvez le ré-exporter en JSON i18next, XLIFF, ou PO. Changez d'outil demain sans réécrire votre code.
Transport custom (avancé)
Besoin de logger les clés manquantes dans votre propre stack d'observabilité, de les protéger derrière votre auth, ou de les stubber dans les tests ? Passez une fonction transport. Le SDK debounce et batche toujours ; vous décidez ce qu'on fait du 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/>