Руководство · Вложенность ключей
По умолчанию Sonenta разбивает ваши ключи по . во вложенное JSON-дерево в бандле CDN — классическая форма i18next. Это идеально для ключей, организованных как checkout.review.confirm, но молча портит ключи, текст которых содержит точку. Это руководство охватывает настройку проекта и соответствующую опцию SDK, чтобы ваши поиски всегда находили нужное.
Ключ — это просто строка. Когда эта строка содержит буквальную точку — версия вроде App Version 6.3.8, цена, имя файла, библейская ссылка вроде Jean 3.16 — разбиение по . превращает один ключ в случайный вложенный объект. Перевод всё ещё хранится, но t("App Version 6.3.8") его больше не находит.
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" }Две настройки на уровне проекта определяют форму бандла CDN. Значения по умолчанию воспроизводят текущее поведение i18next, поэтому существующие проекты не затрагиваются, пока вы явно не включите это.
| Настройка | Значения | По умолчанию |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Задайте их на проекте — в настройках проекта вашего дашборда или через projects API. Выбранный стиль закрепляется в каждом релизе, и каждая опубликованная версия сообщает его обратно, так что любой клиент может настроиться сам.
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": "." }Ключи никогда не разбиваются — каждый хранится и ищется буквально. Выбирайте это, когда ваши ключи содержат точки или являются естественным текстом: версии, цены, имена файлов, библейские или юридические ссылки. App Version 6.3.8 остаётся именно таким.
Ключи разбиваются по разделителю во вложенное JSON-дерево — классическая раскладка i18next. Выбирайте это для намеренно неймспейсированных ключей вроде checkout.review.confirm. Это значение по умолчанию.
@sonenta/react-i18next (>= 0.11.0) принимает опцию keySeparator: false для буквальных / плоских поисков, строку для вложенного режима, по умолчанию ".". Есть также nsSeparator (по умолчанию ":"). SDK сначала буквальный — он пробует точное совпадение bundle[key] перед любым разбиением, поэтому ключи с точками находятся даже во вложенном режиме. При start() он также автоматически определяет key_style / key_separator из опубликованной версии (по возможности).
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 matchАвтоопределение читает метаданные версии и требует ключа с project:read. Если это чтение запрещено (403), SDK аккуратно откатывается на свои значения по умолчанию — поэтому при сомнениях задавайте keySeparator явно, чтобы он соответствовал вашему бандлу, а не полагайтесь на определение.
bundle_key_style: flat на проекте и keySeparator={false} в SDK. Буквально с обеих сторон — никаких сюрпризов. checkout.review.confirm)? Оставьте вложенный режим по умолчанию; менять нечего.