Clés plates ou imbriquées

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.

Le piège des clés à points

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.

// your source key: a literal label with dots in it
{ "App Version 6.3.8": "App Version 6.3.8" }

// nested bundle (default): split on "." → broken tree
{ "App Version 6": { "3": { "8": "App Version 6.3.8" } } }

// flat bundle: the key stays literal, lookups just work
{ "App Version 6.3.8": "App Version 6.3.8" }

Le réglage du projet

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.

# the version object reports the active key style
GET /v1/projects/<project_uuid>/versions/main

{ "slug": "main", "key_style": "flat", "key_separator": "." }

Choisir plat ou imbriqué

bundle_key_style: flat. 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.

bundle_key_style: nested. 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.

Aligner le SDK

@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).

// src/main.tsx: match the bundle in @sonenta/react-i18next >= 0.11.0
import { SonentaProvider } from "@sonenta/react-i18next";

<SonentaProvider
  projectUuid="<project_uuid>"
  token={import.meta.env.VITE_SONENTA_TOKEN}
  keySeparator={false}   // literal lookup, for dotted / natural-text keys
  nsSeparator=":"        // default; set false to disable ns parsing too
>
  <App />
</SonentaProvider>

// then t() treats the whole string as one key, no splitting
t("App Version 6.3.8");   // ✓ exact match

Note

L'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.

Recommandation

• Vos clés contiennent des points ? Mettez bundle_key_style: flat sur le projet et keySeparator={false} dans le SDK. Littéral des deux côtés, aucune surprise.
• Clés proprement namespacées (checkout.review.confirm) ? Gardez le défaut imbriqué ; rien à changer.
• Vous migrez une app existante ? Les valeurs par défaut préservent votre comportement actuel. Passez à flat seulement quand vous rencontrez une clé à points, puis re-publiez et ajustez l'option SDK en même temps.

Ensuite

• Guide: Migrer depuis i18next : Amenez un catalogue existant dans Sonenta en une commande.
• Référence: CLI : Import, push, pull et publication depuis votre terminal.
• Guide: Mettre à jour la valeur source : Modifier le texte source d'une clé après sa création.