bundle_key_style: flat
key 永远不会被切分——每个 key 都按字面存储和查找。当你的 key 含有点号或本身就是自然文本时选择它：版本号、价格、文件名、圣经或法律引用。App Version 6.3.8 就保持其原样。
指南 · key 嵌套
扁平 key 还是嵌套 key
默认情况下，Sonenta 会按 . 将你的 key 切分到 CDN bundle 中的一个嵌套 JSON 树里——这是经典的 i18next 形态。对于像 checkout.review.confirm 这样有组织的 key 很合适，但它会悄无声息地破坏那些文本中含有点号的 key。本指南介绍项目设置以及对应的 SDK 选项，以确保你的查找始终能解析成功。
带点号 key 的陷阱
key 不过是一个字符串。当该字符串包含一个字面点号时——比如像 App Version 6.3.8 这样的版本号、一个价格、一个文件名、像 Jean 3.16 这样的圣经经文引用——按 . 切分会把一个 key 变成一个意外的嵌套对象。翻译仍然被存储着，但 t("App Version 6.3.8") 再也找不到它了。
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" }项目设置
两个项目级设置控制着 CDN bundle 的形态。默认值复现当前的 i18next 行为，因此在你显式选择启用之前，已有项目不受影响。
| 设置 | 取值 | 默认值 |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
在项目上设置它们——在你 dashboard 的项目设置中，或通过 projects API。所选的风格会被固化进每一个 release，且每个已发布的版本都会回报它，因此任何客户端都能自我配置。
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": "." }选择扁平还是嵌套
bundle_key_style: nested
key 会按分隔符切分到一个 JSON 树中——经典的 i18next 布局。为像 checkout.review.confirm 这样刻意做了 namespace 划分的 key 选择它。这是默认值。
在 SDK 中保持一致
@sonenta/react-i18next（>= 0.11.0）接受一个 keySeparator 选项：false 表示字面 / 扁平查找，字符串表示嵌套，默认 "."。还有 nsSeparator（默认 ":"）。SDK 是字面优先的——它会在做任何切分之前先尝试精确的 bundle[key] 匹配，因此带点号的 key 即使在嵌套模式下也能解析成功。在 start() 时，它还会从已发布的版本中自动检测 key_style / key_separator（尽力而为）。
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 match自动检测会读取版本元数据，并需要一个带 project:read 的 key。如果该读取被拒绝（403），SDK 会优雅地回退到它的默认值——所以拿不准时，请显式设置 keySeparator 以匹配你的 bundle，而不是依赖检测。
建议
- key 含有点号？在项目上设置
bundle_key_style: flat，并在 SDK 中设置keySeparator={false}。两端都按字面处理——没有意外。 - 干净地做了 namespace 划分的 key（
checkout.review.confirm）？保持嵌套默认值；无需改动。 - 正在迁移一个现有的 app？默认值会保留你当前的行为。仅在遇到带点号的 key 时才切换到 flat，然后重新发布并同时更新 SDK 选项。