الانتقال من i18next

قبل أن تبدأ

ثلاثة أشياء، وستكون جاهزًا للاستيراد:

• مشروع. أنشئ واحدًا في لوحة التحكم وانسخ project_uuid الخاص به.
• مفتاح API بنطاق mcp:*. تمر الـ CLI عبر سطح MCP — فمفتاح مقيّد بالمشروع يُرجع 403. يشرح مرجع الـ CLI كيفية إنشاء واحد.
• Node 18+ وملفات i18next الموجودة لديك، مرتّبة بصيغة <lang>/<namespace>.json (تُعالَج التراتيب غير المعتادة أيضًا).

1. التثبيت والتهيئة

ثبّت الـ CLI عالميًا، وولّد إعدادًا يشير إلى مشروعك، وصدّر مفتاحك.

1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>

يكتب sonenta init ملف sonenta.config.json يمكنك إيداعه. في الـ CI، تخطَّ init ومرّر --project إضافةً إلى متغيّر البيئة SONENTA_TOKEN. sonenta وSONENTA_* هي المعتمدة؛ وما زال أمر sonenta القديم ومتغيّرات SONENTA_* يعملان خلال فترة الانتقال.

2. المعاينة، ثم الاستيراد

يقرأ المستورِد مسار كل ملف ليستنتج لغته ونطاق أسمائه، لذا لا تحتاج شجرة locales/ التقليدية إلى أي خيارات. نفّذ تشغيلًا تجريبيًا أولًا لرؤية الخطة، ثم احذف --dry-run لتطبيقها.

1# the importer infers (language, namespace) from each path:2#   <lang>/<namespace>.json3locales/4├─ en/5│  ├─ common.json     → language en · namespace common6│  └─ checkout.json   → language en · namespace checkout7└─ fr/8   ├─ common.json     → language fr · namespace common9   └─ checkout.json   → language fr · namespace checkout

1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout   (en, fr)8  keys           312 created · 0 reused9  translations   624 created · 0 updated · 0 unchanged10  errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace common

قد تكون الأشجار متداخلة أو مُسطّحة — وكلاهما يُستورَد بصورة متطابقة. يضبط --status الحالة الواردة (draft أو translated، الافتراضي translated)؛ ويستهدف --version إصدارًا غير افتراضي. تُخزَّن الجموع المُعبَّر عنها كقاموس CLDR ({ one, other }) كصيغ جمع تلقائيًا.

3. النشر إلى الـ CDN

يملأ الاستيراد المشروع؛ والنشر يجعله قابلًا للتقديم. أصدر نسخة فتنتشر الحزم على الـ CDN العالمي الذي يقرأ منه الـ SDK.

1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.com

الإصدارات لقطات ثابتة لإصدار. أعد النشر كلما استوردت محتوى جديدًا — فكلٌّ من الـ SDK وبنائك الثابت يجلبان أحدث إصدار.

4. التحقق من الحزمة

تأكّد من أن المحتوى منشور. الحزمة المنشورة هي مجرد ملف JSON عام لكل لغة ونطاق أسماء — اجلب واحدًا مباشرةً، أو افتح المشروع في لوحة التحكم.

1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json

حصلت على 404 على لغة؟ إنها ليست من لغات المشروع بعد، أو أن الإصدار لم ينتشر — انتظر بضع ثوانٍ وأعد المحاولة.

5. توجيه الـ SDK إلى Sonenta

استبدِل واجهة i18next الخلفية بموفّر Sonenta. تبقى نداءات t() ومفاتيحك ونطاقات أسمائك كما هي — وتأتي الترجمات الآن من حزمة الـ CDN التي نشرتها لتوّك.

1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5  projectUuid="<project_uuid>"6  token={import.meta.env.VITE_SONENTA_TOKEN}7  defaultLocale="fr"8  namespaces={["common", "checkout"]}9>10  <App />11</SonentaProvider>

مفاتيح تحتوي على نقاط (إصدار، أو سعر، أو مرجع كتابي)؟ عيّن keySeparator={false} وحوّل المشروع إلى مُسطّح — انظر دليل المفاتيح المُسطّحة أو المتداخلة. خلاف ذلك، يعمل الافتراضي المتداخل كما هو.

ما يعالجه المستورِد

• متداخل أو مُسطّح. كلتا صيغتي JSON تُستورَدان إلى المفاتيح نفسها — دون أي معالجة مسبقة.
• الجموع. تصير قواميس الجمع وفق CLDR ({ one, other, … }، مع other الإلزامي) مفاتيح جمع تلقائيًا.
• مرونة لكل ملف. يُبلَّغ عن لغة أو نطاق أسماء غير معروف كخطأ لكل وحدة — ومع ذلك ينجح بقية الاستيراد.
• فحوص المسرد. تمرّ الترجمات المستورَدة عبر مسردك؛ وتُسرَد المخالفات، وتُتخطّى عند الإنفاذ الصارم.
• تنظيف المفاتيح المفقودة. تُحلّ أحداث المفاتيح المفقودة المفتوحة للمفاتيح المستورَدة فور وصول القيم.