دليل · تداخل المفاتيح
افتراضيًا، يقسّم Sonenta مفاتيحك على . إلى شجرة JSON متداخلة في حزمة الـ CDN — الصيغة الكلاسيكية لـ i18next. وهذا مثالي للمفاتيح المنظَّمة مثل checkout.review.confirm، لكنه يشوّه بصمت المفاتيح التي يحتوي نصها على نقطة. يغطّي هذا الدليل إعداد المشروع وخيار الـ SDK المطابق له كي تنجح عمليات البحث لديك دائمًا.
المفتاح ليس إلا سلسلة نصية. وعندما تحتوي تلك السلسلة على نقطة حرفية — إصدار مثل App Version 6.3.8، أو سعر، أو اسم ملف، أو مرجع كتابي مثل Jean 3.16 — يحوّل التقسيم على . مفتاحًا واحدًا إلى كائن متداخل عَرَضي. تبقى الترجمة مخزّنة، لكن 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. تُعيد القيم الافتراضية إنتاج سلوك i18next الحالي، لذا لا تتأثر المشاريع الموجودة حتى تختار صراحةً.
| الإعداد | القيم | الافتراضي |
|---|---|---|
| bundle_key_style | nested | flat | nested |
| bundle_key_separator | string | "." |
اضبطهما على المشروع — في إعدادات المشروع في لوحة تحكمك، أو عبر API المشاريع. يُثبَّت النمط المختار في كل إصدار، ويُرجعه كل إصدار منشور، بحيث يتمكّن أي عميل من إعداد نفسه ذاتيًا.
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": "." }لا تُقسَّم المفاتيح أبدًا — يُخزَّن كلٌّ منها ويُبحَث عنه حرفيًا. اختر هذا حين تحتوي مفاتيحك على نقاط أو تكون نصًا طبيعيًا: إصدارات، أو أسعار، أو أسماء ملفات، أو مراجع كتابية أو قانونية. يبقى App Version 6.3.8 كما هو تمامًا.
تُقسَّم المفاتيح على الفاصل إلى شجرة JSON — الترتيب الكلاسيكي لـ i18next. اختر هذا للمفاتيح المُسنَدة لنطاق أسماء عن قصد مثل checkout.review.confirm. هذه هي القيمة الافتراضية.
يقبل @sonenta/react-i18next (>= 0.11.0) خيار keySeparator: false للبحث الحرفي / المُسطّح، أو سلسلة للمتداخل، والافتراضي ".". وهناك أيضًا nsSeparator (الافتراضي ":"). الـ SDK حرفي أولًا — يحاول مطابقة bundle[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. وإذا رُفضت هذه القراءة (403) يرتدّ الـ SDK بسلاسة إلى قيمه الافتراضية — لذا عند الشك، عيّن keySeparator صراحةً ليطابق حزمتك بدلًا من الاعتماد على الاكتشاف.
bundle_key_style: flat على المشروع و keySeparator={false} في الـ SDK. حرفي على الطرفين — بلا مفاجآت. checkout.review.confirm)؟ أبقِ الافتراضي المتداخل؛ لا شيء لتغييره.