Przewodnik · Zagnieżdżanie kluczy
Domyślnie Sonenta dzieli Twoje klucze po znaku . na zagnieżdżone drzewo JSON w pakiecie CDN — klasyczna forma i18next. Świetnie sprawdza się to dla uporządkowanych kluczy w rodzaju checkout.review.confirm, ale po cichu psuje klucze, których tekst zawiera kropkę. Ten przewodnik omawia ustawienie projektu i odpowiadającą mu opcję SDK, aby Twoje wyszukiwania zawsze się rozwiązywały.
Klucz to po prostu ciąg znaków. Gdy ten ciąg zawiera dosłowną kropkę — wersja typu App Version 6.3.8, cena, nazwa pliku, odniesienie biblijne typu Jean 3.16 — podział po znaku . zamienia jeden klucz w przypadkowy zagnieżdżony obiekt. Tłumaczenie nadal jest zapisane, ale t("App Version 6.3.8") już go nie znajduje.
bundle.json 1// your source key — a literal label with dots in it2{ "App Version 6.3.8": "App Version 6.3.8" } 4// nested bundle (default) — split on "." → broken tree5{ "App Version 6": { "3": { "8": "App Version 6.3.8" } } } 7// flat bundle — the key stays literal, lookups just work8{ "App Version 6.3.8": "App Version 6.3.8" }Dwa ustawienia na poziomie projektu kontrolują kształt pakietu CDN. Wartości domyślne odtwarzają obecne zachowanie i18next, więc istniejące projekty pozostają nienaruszone, dopóki świadomie się nie zdecydujesz.
| Ustawienie | Wartości | Domyślnie |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Ustaw je na projekcie — w ustawieniach projektu w panelu lub przez API projektów. Wybrany styl jest wbudowany w każde wydanie, a każda opublikowana wersja go raportuje, dzięki czemu dowolny klient może się sam skonfigurować.
versions/main 1# the version object reports the active key style2GET /v1/projects/<project_uuid>/versions/main 4{ "slug": "main", "key_style": "flat", "key_separator": "." }Klucze nigdy nie są dzielone — każdy jest zapisywany i wyszukiwany dosłownie. Wybierz to, gdy Twoje klucze zawierają kropki lub są naturalnym tekstem: wersje, ceny, nazwy plików, odniesienia biblijne lub prawne. App Version 6.3.8 pozostaje dokładnie tym.
Klucze są dzielone po separatorze na drzewo JSON — klasyczny układ i18next. Wybierz to dla celowo namespace'owanych kluczy w rodzaju checkout.review.confirm. To jest wartość domyślna.
@sonenta/react-i18next (>= 0.11.0) przyjmuje opcję keySeparator: false dla dosłownych / płaskich wyszukiwań, ciąg znaków dla zagnieżdżonych, domyślnie ".". Jest też nsSeparator (domyślnie ":"). SDK jest najpierw dosłowne — próbuje dokładnego dopasowania bundle[key] przed jakimkolwiek podziałem, więc klucze z kropkami rozwiązują się nawet w trybie zagnieżdżonym. Przy start() automatycznie wykrywa również key_style / key_separator z opublikowanej wersji (best-effort).
main.tsx 1// src/main.tsx — match the bundle in @sonenta/react-i18next >= 0.11.02import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5 projectUuid="<project_uuid>"6 token={import.meta.env.VITE_SONENTA_TOKEN}7 keySeparator={false} // literal lookup — for dotted / natural-text keys8 nsSeparator=":" // default; set false to disable ns parsing too9>10 <App />11</SonentaProvider> 13// then t() treats the whole string as one key — no splitting14t("App Version 6.3.8"); // ✓ exact matchAutomatyczne wykrywanie odczytuje metadane wersji i wymaga klucza z project:read. Jeśli ten odczyt zostanie odrzucony (403), SDK eleganckie wraca do swoich wartości domyślnych — więc w razie wątpliwości ustaw keySeparator jawnie, aby pasował do Twojego pakietu, zamiast polegać na wykrywaniu.
bundle_key_style: flat na projekcie oraz keySeparator={false} w SDK. Dosłownie z obu stron — żadnych niespodzianek. checkout.review.confirm)? Zostaw domyślny tryb zagnieżdżony; nic nie zmieniaj.