Guida · Annidamento delle chiavi
Per impostazione predefinita, Sonenta divide le vostre chiavi sul . in un albero JSON annidato nel bundle CDN — la forma classica di i18next. Perfetto per chiavi organizzate come checkout.review.confirm, ma rovina silenziosamente le chiavi il cui testo contiene un punto. Questa guida copre l'impostazione di progetto e l'opzione SDK corrispondente affinché le vostre ricerche vadano sempre a buon fine.
Una chiave è solo una stringa. Quando quella stringa contiene un punto letterale — una versione come App Version 6.3.8, un prezzo, un nome di file, un riferimento biblico come Jean 3.16 — la divisione sul . trasforma un'unica chiave in un oggetto annidato accidentale. La traduzione è comunque memorizzata, ma t("App Version 6.3.8") non la trova più.
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" }Due impostazioni a livello di progetto determinano la forma del bundle CDN. I valori predefiniti riproducono il comportamento i18next attuale: i progetti esistenti non cambiano finché non aderite esplicitamente.
| Impostazione | Valori | Predefinito |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Impostatele sul progetto — nelle impostazioni di progetto della vostra dashboard, oppure tramite l'API progetti. Lo stile scelto viene fissato in ogni release, e ogni versione pubblicata lo restituisce, in modo che qualsiasi client possa auto-configurarsi.
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": "." }Le chiavi non vengono mai divise — ciascuna è memorizzata e ricercata letteralmente. Scegliete questa opzione quando le vostre chiavi contengono punti o sono testo naturale: versioni, prezzi, nomi di file, riferimenti biblici o giuridici. App Version 6.3.8 resta esattamente questo.
Le chiavi vengono divise sul separatore in un albero JSON — la disposizione i18next classica. Scegliete questa opzione per chiavi deliberatamente in namespace come checkout.review.confirm. È il valore predefinito.
@sonenta/react-i18next (>= 0.11.0) accetta un'opzione keySeparator: false per ricerche letterali / piatte, una stringa per l'annidato, predefinito ".". C'è anche nsSeparator (predefinito ":"). L'SDK è letterale prima di tutto — tenta una corrispondenza esatta bundle[key] prima di qualsiasi divisione, quindi le chiavi con punti vanno a buon fine anche in modalità annidata. Al start(), auto-rileva anche key_style / key_separator dalla versione pubblicata (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 matchL'auto-rilevamento legge i metadati di versione e richiede una chiave con project:read. Se questa lettura viene negata (403), l'SDK ripiega in modo pulito sui propri valori predefiniti — quindi nel dubbio impostate keySeparator esplicitamente per corrispondere al vostro bundle invece di affidarvi al rilevamento.
bundle_key_style: flat sul progetto e keySeparator={false} nell'SDK. Letterale su entrambi i lati — nessuna sorpresa. checkout.review.confirm)? Mantenete il valore predefinito annidato; niente da cambiare.