Guía · Anidamiento de claves
Por defecto, Sonenta divide tus claves por el . en un árbol JSON anidado dentro del bundle de CDN — la forma clásica de i18next. Perfecto para claves organizadas como checkout.review.confirm, pero rompe silenciosamente las claves cuyo texto contiene un punto. Esta guía cubre el ajuste del proyecto y la opción del SDK correspondiente para que tus búsquedas siempre se resuelvan.
Una clave no es más que una cadena. Cuando esa cadena contiene un punto literal — una versión como App Version 6.3.8, un precio, un nombre de archivo, una referencia bíblica como Jean 3.16 — dividir por el . transforma una sola clave en un objeto anidado accidental. La traducción sigue almacenada, pero t("App Version 6.3.8") ya no la encuentra.
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" }Dos ajustes a nivel de proyecto determinan la forma del bundle de CDN. Los valores por defecto reproducen el comportamiento actual de i18next: los proyectos existentes no cambian hasta que optes explícitamente por ello.
| Ajuste | Valores | Por defecto |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Configúralos en el proyecto — en los ajustes de proyecto de tu dashboard, o mediante la API de proyectos. El estilo elegido queda fijado en cada release, y cada versión publicada lo devuelve, de modo que cualquier cliente puede autoconfigurarse.
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": "." }Las claves nunca se dividen — cada una se almacena y se busca literalmente. Elige esto cuando tus claves contienen puntos o son texto natural: versiones, precios, nombres de archivo, referencias bíblicas o jurídicas. App Version 6.3.8 sigue siendo exactamente eso.
Las claves se dividen por el separador en un árbol JSON — la disposición clásica de i18next. Elige esto para claves deliberadamente namespacadas como checkout.review.confirm. Es el valor por defecto.
@sonenta/react-i18next (>= 0.11.0) acepta una opción keySeparator: false para búsquedas literales / planas, una cadena para anidado, por defecto ".". También está nsSeparator (por defecto ":"). El SDK es literal primero — intenta una coincidencia exacta bundle[key] antes de cualquier división, así que las claves con puntos se resuelven incluso en modo anidado. En start() también autodetecta key_style / key_separator a partir de la versión publicada (en la medida de lo posible).
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 matchLa autodetección lee los metadatos de versión y necesita una clave con project:read. Si esa lectura se deniega (403), el SDK recae limpiamente en sus valores por defecto — así que ante la duda, fija keySeparator explícitamente para que coincida con tu bundle en lugar de confiar en la detección.
bundle_key_style: flat en el proyecto y keySeparator={false} en el SDK. Literal en ambos lados — sin sorpresas. checkout.review.confirm)? Mantén el valor por defecto anidado; nada que cambiar.