Anleitung · Schlüssel-Verschachtelung
Standardmäßig teilt Sonenta Ihre Schlüssel am . in einen verschachtelten JSON-Baum im CDN-Bundle auf — die klassische i18next-Form. Das ist perfekt für organisierte Schlüssel wie checkout.review.confirm, aber es verstümmelt stillschweigend Schlüssel, deren Text einen Punkt enthält. Diese Anleitung behandelt die Projekteinstellung und die passende SDK-Option, damit Ihre Lookups immer aufgelöst werden.
Ein Schlüssel ist nur eine Zeichenkette. Wenn diese Zeichenkette einen wörtlichen Punkt enthält — eine Version wie App Version 6.3.8, ein Preis, ein Dateiname, eine Bibelstelle wie Jean 3.16 — verwandelt das Aufteilen am . einen einzelnen Schlüssel in ein versehentliches verschachteltes Objekt. Die Übersetzung wird weiterhin gespeichert, aber t("App Version 6.3.8") findet sie nicht mehr.
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" }Zwei Einstellungen auf Projektebene bestimmen die Form des CDN-Bundles. Die Standardwerte bilden das aktuelle i18next-Verhalten nach: bestehende Projekte bleiben unverändert, bis Sie sich ausdrücklich dafür entscheiden.
| Einstellung | Werte | Standard |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
Stellen Sie sie am Projekt ein — in den Projekteinstellungen Ihres Dashboards oder über die Projekt-API. Der gewählte Stil ist in jedem Release fest verankert, und jede veröffentlichte Version meldet ihn zurück, sodass sich jeder Client selbst konfigurieren kann.
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": "." }Schlüssel werden niemals aufgeteilt — jeder wird wörtlich gespeichert und nachgeschlagen. Wählen Sie dies, wenn Ihre Schlüssel Punkte enthalten oder natürlicher Text sind: Versionen, Preise, Dateinamen, Bibel- oder Rechtsverweise. App Version 6.3.8 bleibt genau das.
Schlüssel werden am Trennzeichen in einen JSON-Baum aufgeteilt — die klassische i18next-Anordnung. Wählen Sie dies für bewusst namespaceierte Schlüssel wie checkout.review.confirm. Dies ist der Standard.
@sonenta/react-i18next (>= 0.11.0) akzeptiert eine keySeparator-Option: false für wörtliche / flache Lookups, eine Zeichenkette für verschachtelte, Standard ".". Es gibt außerdem nsSeparator (Standard ":"). Das SDK ist wörtlich zuerst — es versucht eine exakte bundle[key]-Übereinstimmung vor jeder Aufteilung, sodass Schlüssel mit Punkten selbst im verschachtelten Modus aufgelöst werden. Bei start() erkennt es außerdem key_style / key_separator aus der veröffentlichten Version automatisch (nach bestem Bemühen).
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 matchDie automatische Erkennung liest die Versions-Metadaten und benötigt einen Schlüssel mit project:read. Wird dieser Lesezugriff verweigert (403), fällt das SDK sauber auf seine Standardwerte zurück — setzen Sie im Zweifelsfall daher keySeparator ausdrücklich passend zu Ihrem Bundle, statt sich auf die Erkennung zu verlassen.
bundle_key_style: flat am Projekt und keySeparator={false} im SDK. Wörtlich auf beiden Seiten — keine Überraschungen. checkout.review.confirm)? Behalten Sie den verschachtelten Standard bei; nichts zu ändern.