React + i18next

Installa

Richiede <strong>Node 20 LTS</strong> o più recente. Si installano due binari: <code>verbumia</code> e l'alias più corto <code>vrb</code> — intercambiabili.

1npm i @verbumia/react-i18next

2. Avvolgi la tua app

VerbumiaProvider prende un projectId e una apiKey. Tutto il resto ha default sensati: auto-rilevamento del locale dal browser, namespace caricati on-demand dal tuo CDN, handler delle chiavi mancanti con debounce e POST automatico.

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);

3. Usa l'hook

useTranslation() restituisce { t, i18n }. Forma familiare se hai usato react-i18next. i18n.ready ti dice quando i namespace iniziali sono idratati; i18n.changeLanguage() cambia locale a runtime.

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}

Cosa ottieni gratis

• Cattura delle chiavi mancanti. Ogni chiave che chiami e che non è nel dizionario viene messa in coda, debounciata (5s di default) e inviata via POST alla coda delle mancanti della tua dashboard. Sicuro in produzione — il tuo fallback continua a renderizzare.
• Namespace serviti da CDN. I bundle di traduzione sono recuperati da cdn.verbumia.ca con caching HTTP e stale-while-revalidate. Nessun bundling a build-time richiesto.
• Auto-rilevamento del locale. Se non passi defaultLocale, l'SDK legge navigator.language e ricade sul default del tuo progetto.
• Export aperti. Qualunque cosa pushi su Verbumia, la puoi esportare in JSON i18next, XLIFF o PO. Cambia tool domani senza riscrivere il tuo codice.

Transport personalizzato (avanzato)

Serve loggare le chiavi mancanti nel tuo stack di observability, proteggerle dietro la tua auth o stubbarle nei test? Passa una funzione transport. L'SDK fa comunque debounce e batching; tu decidi cosa fare del batch.

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/>