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.