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.