Guide · Imbrication des clés
Par défaut, Sonenta découpe vos clés sur le . en un arbre JSON imbriqué dans le bundle CDN — la forme classique d'i18next. Parfait pour des clés organisées comme checkout.review.confirm, mais cela casse silencieusement les clés dont le texte contient un point. Ce guide couvre le réglage du projet et l'option SDK correspondante pour que vos recherches aboutissent toujours.
Une clé n'est qu'une chaîne. Quand cette chaîne contient un point littéral — une version comme App Version 6.3.8, un prix, un nom de fichier, une référence biblique comme Jean 3.16 — le découpage sur le . transforme une clé unique en objet imbriqué accidentel. La traduction est toujours stockée, mais t("App Version 6.3.8") ne la trouve plus.
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" }Deux réglages au niveau du projet déterminent la forme du bundle CDN. Les valeurs par défaut reproduisent le comportement i18next actuel : les projets existants ne changent pas tant que vous n'optez pas explicitement.
| Réglage | Valeurs | Défaut |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Réglez-les sur le projet — dans les paramètres de projet de votre dashboard, ou via l'API projets. Le style choisi est figé dans chaque release, et chaque version publiée le renvoie, de sorte que n'importe quel client peut s'auto-configurer.
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": "." }Les clés ne sont jamais découpées — chacune est stockée et recherchée littéralement. À choisir quand vos clés contiennent des points ou sont du texte naturel : versions, prix, noms de fichiers, références bibliques ou juridiques. App Version 6.3.8 reste exactement cela.
Les clés sont découpées sur le séparateur en un arbre JSON — la disposition i18next classique. À choisir pour des clés délibérément namespacées comme checkout.review.confirm. C'est la valeur par défaut.
@sonenta/react-i18next (>= 0.11.0) accepte une option keySeparator : false pour des recherches littérales / plates, une chaîne pour l'imbriqué, défaut ".". Il y a aussi nsSeparator (défaut ":"). Le SDK est littéral d'abord — il tente une correspondance exacte bundle[key] avant tout découpage, donc les clés à points aboutissent même en mode imbriqué. Au start(), il auto-détecte aussi key_style / key_separator depuis la version publiée (au mieux).
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 matchL'auto-détection lit les métadonnées de version et nécessite une clé avec project:read. Si cette lecture est refusée (403), le SDK retombe proprement sur ses valeurs par défaut — en cas de doute, fixez donc keySeparator explicitement pour correspondre à votre bundle plutôt que de compter sur la détection.
bundle_key_style: flat sur le projet et keySeparator={false} dans le SDK. Littéral des deux côtés — aucune surprise. checkout.review.confirm) ? Gardez le défaut imbriqué ; rien à changer.