Avvio rapido
React + i18next
Installa l'SDK, avvolgi la tua app in <SonentaProvider /> e chiama useTranslation(). Le chiavi mancanti arrivano alla tua dashboard automaticamente — nessun cablaggio extra.
1. Installa
Una sola dipendenza. Niente ginnastica peer-dep — l'SDK include tutto il lato React.
terminal 1npm i @sonenta/react-i18next2. Avvolgi la tua app
SonentaProvider 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 { SonentaProvider } from "@sonenta/react-i18next";3import { createRoot } from "react-dom/client";4import { App } from "./App"; 6createRoot(document.getElementById("root")!).render(7 <SonentaProvider8 projectUuid="proj_xxx"9 token={import.meta.env.VITE_SONENTA_TOKEN}10 defaultLocale="en"11 namespaces={["common"]}12 >13 <App />14 </SonentaProvider>15); Tutte le props di SonentaProvider
| Prop | Type | Default |
|---|---|---|
| projectUuid | string | — obbligatoria |
| token | string | — obbligatoria |
| defaultLocale | string | browser |
| defaultNS | string | "common" |
| namespaces | string[] | ["common"] |
| cdnUrl | string | cdn.sonenta.com |
| baseUrl | string | api.sonenta.com |
| 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 "@sonenta/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.sonenta.comcon 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 Sonenta, 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<SonentaProvider3 projectUuid="proj_xxx"4 token={import.meta.env.VITE_SONENTA_TOKEN}5 debounceMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>