API REST
React + i18next
Il riferimento API completo sarà auto-generato dalla nostra spec OpenAPI 3.1 nel momento in cui la superficie sarà stabile. Preferiamo shippare un placeholder piuttosto che fake-doc endpoint che possono ancora muoversi. Nel frattempo, ecco la forma, cosa coprirà e cosa fare oggi.
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.
terminal 1npm i @verbumia/react-i18next2. 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.
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); Tutte le props di VerbumiaProvider
| Prop | Type | Default |
|---|---|---|
| projectId | string | — obbligatoria |
| apiKey | string | — obbligatoria |
| 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 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.
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}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.cacon caching HTTP e stale-while-revalidate. Nessun bundling a build-time richiesto. - Auto-rilevamento del locale. Se non passi
defaultLocale, l'SDK leggenavigator.languagee 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.
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/>