Przewodnik · Migracja
Migracja z i18next
Działasz już w produkcji z i18next? @sonenta/react-i18next to bezpośrednie zastąpienie (drop-in) react-i18next — to samo API useTranslation() i t(): po prostu podmieniasz provider, a tłumaczenia przychodzą na żywo z CDN. Wnieś swoje istniejące pliki locales/ do Sonenta jednym poleceniem, a potem zostaw kod takim, jaki jest. Import tworzy brakujące klucze, aktualizuje każde tłumaczenie i jest w pełni idempotentny: możesz go bez obaw uruchamiać ponownie z CI. Oto cała ścieżka: instalacja, import, publikacja, weryfikacja, podpięcie SDK.
Zanim zaczniesz
Trzy rzeczy i jesteś gotowy do importu:
- Projekt. Utwórz go w panelu i skopiuj jego
project_uuid. - Klucz API o zakresie
mcp:*. CLI działa przez powierzchnię MCP — klucz ograniczony do projektu zwraca403. Referencja CLI opisuje, jak taki klucz wygenerować. - Node 18+ oraz Twoje istniejące pliki i18next, ułożone jako
<lang>/<namespace>.json(nietypowe układy też są obsługiwane).
1. Instalacja i inicjalizacja
Zainstaluj CLI globalnie, wygeneruj konfigurację wskazującą na Twój projekt i wyeksportuj swój klucz.
terminal 1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>sonenta init zapisuje plik sonenta.config.json, który możesz scommitować. W CI pomiń init i przekaż --project oraz zmienną środowiskową SONENTA_TOKEN. sonenta i SONENTA_* są kanoniczne; starsze polecenie sonenta i zmienne SONENTA_* nadal działają w okresie przejściowym.
2. Podgląd, a potem import
Importer odczytuje ścieżkę każdego pliku, aby wywnioskować jego język i namespace, więc konwencjonalne drzewo locales/ nie wymaga żadnych opcji. Najpierw wykonaj dry-run, aby zobaczyć plan, a potem usuń --dry-run, aby go zastosować.
your repo 1# the importer infers (language, namespace) from each path:2# <lang>/<namespace>.json3locales/4├─ en/5│ ├─ common.json → language en · namespace common6│ └─ checkout.json → language en · namespace checkout7└─ fr/8 ├─ common.json → language fr · namespace common9 └─ checkout.json → language fr · namespace checkoutterminal 1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout (en, fr)8 keys 312 created · 0 reused9 translations 624 created · 0 updated · 0 unchanged10 errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace commonDrzewa mogą być zagnieżdżone lub płaskie — oba importują się identycznie. --status ustawia status przychodzący (draft lub translated, domyślnie translated); --version wskazuje wersję inną niż domyślna. Liczby mnogie wyrażone jako słownik CLDR ({ one, other }) są automatycznie zapisywane jako formy liczby mnogiej.
3. Publikacja na CDN
Import wypełnia projekt; publikacja czyni go gotowym do serwowania. Wytnij wydanie, a pakiety rozpropagują się na globalnym CDN, z którego czyta SDK.
terminal 1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.comWydania to niezmienne migawki wersji. Publikuj ponownie za każdym razem, gdy zaimportujesz nową treść — zarówno SDK, jak i Twój build statyczny pobierają najnowsze wydanie.
4. Weryfikacja pakietu
Potwierdź, że treść jest na żywo. Opublikowany pakiet to zwykły, publiczny plik JSON dla każdego języka i namespace — pobierz go bezpośrednio albo otwórz projekt w panelu.
terminal 1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json404 dla danego języka? Nie jest on jeszcze jednym z języków projektu albo wydanie się nie rozpropagowało — odczekaj kilka sekund i spróbuj ponownie.
5. Skieruj SDK na Sonenta
Podmień swój backend i18next na provider Sonenta. Twoje wywołania t(), klucze i namespace'y pozostają takie same — tłumaczenia pochodzą teraz z pakietu CDN, który właśnie opublikowałeś.
main.tsx 1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5 projectUuid="<project_uuid>"6 token={import.meta.env.VITE_SONENTA_TOKEN}7 defaultLocale="fr"8 namespaces={["common", "checkout"]}9>10 <App />11</SonentaProvider>Klucze zawierające kropki (wersja, cena, odniesienie biblijne)? Ustaw keySeparator={false} i przełącz projekt na płaski — zobacz przewodnik Klucze płaskie czy zagnieżdżone. W przeciwnym razie domyślny tryb zagnieżdżony po prostu działa.
Możesz uruchomić ponownie w dowolnej chwili
sonenta import jest idempotentny: ponowny import identycznej treści niczego nie zmienia (0 utworzonych, 0 zaktualizowanych, N niezmienionych). Wepnij go w CI, aby utrzymywać Sonenta w synchronizacji z Twoim repozytorium — tworzy tylko to, czego brakuje, i aktualizuje tylko to, co faktycznie się zmieniło.
Co obsługuje importer
- Zagnieżdżone lub płaskie. Obie formy JSON importują się do tych samych kluczy — bez wstępnego przetwarzania.
- Liczby mnogie. Słowniki liczby mnogiej CLDR (
{ one, other, … }, z wymaganymother) stają się automatycznie kluczami liczby mnogiej. - Odporność na poziomie pliku. Nieznany język lub namespace jest raportowany jako błąd na poziomie jednostki — reszta importu i tak dochodzi do skutku.
- Kontrole glosariusza. Importowane tłumaczenia przechodzą przez Twój glosariusz; naruszenia są wylistowane, a przy ścisłym egzekwowaniu pomijane.
- Sprzątanie brakujących kluczy. Otwarte zdarzenia brakującego klucza dla importowanych kluczy automatycznie się rozwiązują, gdy tylko nadejdą wartości.