Snabbstart
React + i18next
Installera SDK:n, lägg din app i <SonentaProvider /> och anropa useTranslation(). Saknade nycklar går automatiskt till din dashboard, ingen extra koppling.
1. Installera
En enda dependency. Ingen peer-dep-akrobatik, SDK:n innehåller allt på React-sidan.
terminal 1npm i @sonenta/react-i18next2. Linda din app
SonentaProvider tar en projectUuid och en defaultLocale; din API-nyckel skickas i propen token. Det finns ingen automatisk locale-detektering, defaultLocale är obligatorisk. Namespaces hämtas vid behov från CDN, och saknade nycklar skickas i satser, var 5:e sekund eller var 50:e händelse, beroende på vad som inträffar först.
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); Alla SonentaProvider-props
| Prop | Typ | Default |
|---|---|---|
| projectUuid | string | krävs |
| defaultLocale | Locale | krävs |
| children | ReactNode | krävs |
| token | string | req. unless transport |
| namespaces | Namespace[] | ["common"] |
| defaultNS | Namespace | - |
| keySeparator | string | false | "." (auto-detected) |
| nsSeparator | string | false | ":" |
| apiBase | string | https://api.sonenta.dev |
| cdnBase | string | https://cdn.sonenta.com |
| fetchImpl | typeof fetch | global fetch |
| env | "prod" | "dev" | "prod" |
| version | string | "main" |
| versionSlug (deprecated) | string | - |
| missingHandler | "send" | "log" | "off" | "send" |
| transport | (batch: MissingKeyEvent[]) => … | built-in POST |
| flushIntervalMs | number | 5000 |
| flushBatchSize | number | 50 |
| missingEventsBufferSize | number | 200 |
| initialBundles | Record<Locale, Record<...>> | - |
| languageCatalog | LanguageMeta[] | - |
| disableLanguageCatalog | boolean | false |
| disableLanguageManifest | boolean | false |
| fallbackLng | Locale | Locale[] | - |
| surface | Surface | - |
| surfaceBreakpoints | SurfaceBreakpoints | boolean | - |
| a11ySurfaces | A11ySurface[] | [] |
| plainLanguage | boolean | false |
| plugins | SonentaPlugin[] | - |
| interpolation | { format?: (…) => string } | - |
-
tokenis required unless you supply your owntransport. Passing neither throws at mount. It authenticates only the missing-key POST, the key-style probe, and the runtime fetch inenv: "dev". - Only
formatis configurable underinterpolation.escapeValueis alwaysfalse, because React escapes already. - Regional variants already fall back to their base (
fr-CAtofr) with no configuration.fallbackLngis appended after that chain, it does not replace it.
3. Använd hooken
useTranslation() returnerar { t, i18n }. Bekant form om du använt react-i18next. i18n.ready säger när de initiala namespacen är hydrerade; i18n.changeLanguage() byter locale i 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}Vad du får gratis
- Fångst av saknade nycklar. Varje nyckel du anropar som inte finns i ordlistan köas, debouncas (5s default) och POST:as till dashboardens missing-kö. Produktionssäkert, din fallback renderas fortfarande.
- Namespaces via CDN. Översättningsbuntar hämtas från
cdn.sonenta.commed HTTP-caching och stale-while-revalidate. Ingen build-time-bundling krävs. - Auto-detekterad locale. Om du inte skickar
defaultLocaleläser SDK:nnavigator.languageoch faller tillbaka på projektets default. - Öppna exporter. Allt du pushar till Sonenta kan du exportera tillbaka till JSON i18next, XLIFF eller PO. Byt verktyg imorgon utan att skriva om koden.
Three failures that stay silent
Each of these leaves your page looking perfectly fine. None of them raises an error you will notice.
- A broken token barely warns, and never throws. Passing no
tokenand notransportthrows at mount. A token that is present but shaped like an unset environment variable ("undefined","null") produces aconsole.warn. Both guards exist only from@sonenta/react-i18next2.6.1 (@sonenta/i18n-core1.1.3); below that, nothing is reported at all. And an empty string, the?? ""you write to satisfy TypeScript, is covered by no warning at any version. In every case the server returns 401, the SDK degrades gracefully, the CDN keeps serving, and your app stays unauthenticated. Do not grep your logs forApiKey undefined: with?? ""that is a guaranteed false negative. Read theAuthorizationheader of the network request in your deployed build instead. - A missing namespace looks like an empty one. Namespace bundles are fetched from the CDN only when
envis"prod"; in"dev"they come from the authenticated runtime API instead. And a 404 resolves to an empty bundle, with no error and no retry, so a namespace you have not published yet is indistinguishable from one that is genuinely empty. - Undeclared a11y surfaces fall back quietly. The accessibility accessors only read surfaces you asked for at load time, via
a11ySurfaces. Without it the overlay is never downloaded andt.aria(key)simply returns the visible text, with no error and no warning. The symptom is not a crash, it is anaria-labelthat duplicates the label next to it.
Egen transport (avancerat)
Behöver du logga saknade nycklar till din egen observability-stack, gate:a dem bakom din auth eller stub:a dem i tester? Skicka in en transport-funktion. SDK:n debouncar och batchar fortfarande; du bestämmer vad som händer med batchen.
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 flushIntervalMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>