Szybki start
React + i18next
Zainstaluj SDK, opakuj aplikację w <SonentaProvider /> i wywołaj useTranslation(). Brakujące klucze trafiają do panelu automatycznie — bez dodatkowego okablowania.
1. Instalacja
Jedna zależność. Bez akrobacji peer-dep — SDK zawiera wszystko po stronie React.
terminal 1npm i @sonenta/react-i18next2. Opakuj aplikację
SonentaProvider przyjmuje projectId i apiKey. Reszta ma rozsądne wartości domyślne: auto-detekcja locale z przeglądarki, namespacy ładowane leniwie z CDN, handler brakujących kluczy debounced i wysyłany automatycznie POST-em.
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); Wszystkie propsy SonentaProvider
| Prop | Typ | Domyślnie |
|---|---|---|
| projectUuid | string | — wymagane |
| token | string | — wymagane |
| 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. Użyj hooka
useTranslation() zwraca { t, i18n }. Znajomy kształt, jeśli używałeś react-i18next. i18n.ready mówi, kiedy początkowe namespacy są zhydratowane; i18n.changeLanguage() zmienia locale w 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}Co dostajesz za darmo
- Wyłapywanie brakujących kluczy. Każdy wywołany klucz spoza słownika trafia do kolejki, jest debounced (domyślnie 5s) i wysyłany POST-em do kolejki braków w panelu. Bezpieczne na produkcji — twój fallback dalej się renderuje.
- Namespacy z CDN. Paczki tłumaczeń pobierane są z
cdn.sonenta.comz cache'owaniem HTTP i stale-while-revalidate. Bez bundlowania w buildzie. - Auto-detekcja locale. Jeśli nie podasz
defaultLocale, SDK czytanavigator.languagei wraca do domyślnej wartości projektu. - Otwarte eksporty. Cokolwiek wypchniesz do Sonenta, możesz wyeksportować z powrotem jako JSON i18next, XLIFF lub PO. Zmień narzędzie jutro bez przepisywania kodu.
Własny transport (zaawansowane)
Chcesz logować brakujące klucze do własnego stacka obserwowalności, schować je za swoją autoryzacją albo zastubować w testach? Podaj funkcję transport. SDK dalej debounce'uje i batchuje; ty decydujesz, co dzieje się z batchem.
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/>