REST API
React + i18next
Pełna referencja API zostanie auto-generowana z naszej specki OpenAPI 3.1, gdy tylko surface się ustabilizuje. Wolimy wypuścić placeholder niż fake-dokumentować endpointy, które jeszcze mogą się zmienić. Tymczasem oto kształt, co obejmie i co zrobić dziś.
Instalacja
Wymaga <strong>Node 20 LTS</strong> lub nowszego. Instalowane są dwa binarne: <code>verbumia</code> i krótszy alias <code>vrb</code> — wymienne.
terminal 1npm i @verbumia/react-i18next2. Opakuj aplikację
VerbumiaProvider 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 { 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); Wszystkie propsy VerbumiaProvider
| Prop | Typ | Domyślnie |
|---|---|---|
| projectId | string | — wymagane |
| apiKey | string | — wymagane |
| 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. 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 "@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}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.verbumia.caz 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 Verbumia, 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<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/>