Démarrage rapide
React + i18next
Installez le SDK, enveloppez votre app dans <VerbumiaProvider />, et appelez useTranslation(). Les clés manquantes remontent à votre tableau de bord automatiquement — aucun branchement supplémentaire.
1. Installer
Une seule dépendance. Pas d'acrobaties peer-dep — le SDK contient tout côté React.
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.dev |
| 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/>