Guia · Aninhamento de chaves
Por omissão, a Sonenta divide as suas chaves no . numa árvore JSON aninhada no bundle CDN — a forma clássica do i18next. É perfeito para chaves organizadas como checkout.review.confirm, mas quebra silenciosamente as chaves cujo texto contém um ponto. Este guia cobre a definição do projeto e a opção SDK correspondente para que as suas pesquisas resolvam sempre.
Uma chave é apenas uma string. Quando essa string contém um ponto literal — uma versão como App Version 6.3.8, um preço, um nome de ficheiro, uma referência bíblica como Jean 3.16 — a divisão no . transforma uma única chave num objeto aninhado acidental. A tradução continua armazenada, mas t("App Version 6.3.8") já não a encontra.
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" }Duas definições ao nível do projeto controlam a forma do bundle CDN. Os valores por omissão reproduzem o comportamento atual do i18next, pelo que os projetos existentes não são afetados até que opte explicitamente.
| Definição | Valores | Por omissão |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Defina-as no projeto — nas definições de projeto do seu dashboard, ou através da API de projetos. O estilo escolhido é fixado em cada release, e cada versão publicada devolve-o, de modo que qualquer cliente se pode autoconfigurar.
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": "." }As chaves nunca são divididas — cada uma é armazenada e pesquisada literalmente. Escolha isto quando as suas chaves contêm pontos ou são texto natural: versões, preços, nomes de ficheiros, referências bíblicas ou jurídicas. App Version 6.3.8 permanece exatamente isso.
As chaves são divididas no separador numa árvore JSON — a disposição clássica do i18next. Escolha isto para chaves deliberadamente com namespace como checkout.review.confirm. É o valor por omissão.
@sonenta/react-i18next (>= 0.11.0) aceita uma opção keySeparator: false para pesquisas literais / planas, uma string para aninhado, por omissão ".". Existe também nsSeparator (por omissão ":"). O SDK é literal primeiro — tenta uma correspondência exata bundle[key] antes de qualquer divisão, pelo que as chaves com pontos resolvem mesmo em modo aninhado. No start(), também deteta automaticamente key_style / key_separator a partir da versão publicada (na melhor das hipóteses).
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 matchA deteção automática lê os metadados da versão e precisa de uma chave com project:read. Se essa leitura for recusada (403), o SDK recorre de forma limpa aos seus valores por omissão — por isso, em caso de dúvida, defina keySeparator explicitamente para corresponder ao seu bundle em vez de depender da deteção.
bundle_key_style: flat no projeto e keySeparator={false} no SDK. Literal em ambos os lados — sem surpresas. checkout.review.confirm)? Mantenha o padrão aninhado; nada a alterar.