フラットキーとネストキー

ドット入りキーの罠

キーは単なる文字列です。その文字列にリテラルなドットが含まれる場合、たとえば App Version 6.3.8 のようなバージョン、価格、ファイル名、Jean 3.16 のような聖句参照などでは、. での分割が 1 つのキーを意図しないネストオブジェクトに変えてしまいます。翻訳は依然として保存されていますが、t("App Version 6.3.8") ではもう見つけられません。

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" }

プロジェクト設定

プロジェクトレベルの 2 つの設定が、CDN バンドルの形を制御します。デフォルト値は現在の i18next の挙動を再現するため、明示的にオプトインするまで既存のプロジェクトは影響を受けません。

これらはプロジェクトに設定します。ダッシュボードのプロジェクト設定、またはプロジェクト API 経由で行えます。選択したスタイルはすべてのリリースに焼き込まれ、公開されたすべてのバージョンがそれを返すため、どのクライアントも自己設定できます。

1# the version object reports the active key style2GET /v1/projects/<project_uuid>/versions/main 4{ "slug": "main", "key_style": "flat", "key_separator": "." }

フラットとネストの選択

SDK でも合わせる

@sonenta/react-i18next（>= 0.11.0）は keySeparator オプションを受け付けます：リテラル／フラットな検索には false、ネストには文字列を指定し、デフォルトは "." です。nsSeparator もあります（デフォルト ":"）。SDK はリテラル優先で、分割の前にまず bundle[key] の完全一致を試みるため、ネストモードでもドット入りキーが解決されます。start() 時には、公開されたバージョンから key_style / key_separator を自動検出もします（ベストエフォート）。

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 を持つキーが必要です。その読み取りが拒否された場合（403）、SDK はデフォルト値へ穏やかにフォールバックします。そのため、迷う場合は検出に頼らず、バンドルに合わせて keySeparator を明示的に設定してください。