تخطَّ إلى المحتوى
Sonenta
Language
ابدأابدأ مجانًاابدأ مجانًا

دليل · الانتقال

الانتقال من i18next

هل أنت في الإنتاج بالفعل مع i18next؟ @sonenta/react-i18next هو بديل مباشر (drop-in) لـ react-i18next, واجهة useTranslation() وt() نفسها: تبدّل الموفّر فقط فتأتي ترجماتك مباشرةً من الـ CDN. أحضِر ملفات locales/ الموجودة لديك إلى Sonenta بأمر واحد، ثم أبقِ شيفرتك كما هي. ينشئ الاستيراد المفاتيح المفقودة، ويحدّث كل ترجمة، وهو عديم التأثير الجانبي تمامًا: فيمكنك إعادة تشغيله من الـ CI دون خوف. إليك المسار الكامل: التثبيت، الاستيراد، النشر، التحقق، وربط الـ SDK.

قبل أن تبدأ

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

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

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

terminal 
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 لتطبيقها.

your repo 
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
terminal 
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.

terminal 
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 عام لكل لغة ونطاق أسماء, اجلب واحدًا مباشرةً، أو افتح المشروع في لوحة التحكم.

terminal 
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 التي نشرتها لتوّك.

main.tsx 
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} وحوّل المشروع إلى مُسطّح, انظر دليل المفاتيح المُسطّحة أو المتداخلة. خلاف ذلك، يعمل الافتراضي المتداخل كما هو.

قابل لإعادة التشغيل في أي وقت

sonenta import عديم التأثير الجانبي: إعادة استيراد محتوى متطابق لا تغيّر شيئًا (0 created, 0 updated, N unchanged). اربطه بالـ CI لإبقاء Sonenta متزامنًا مع مستودعك, فهو لا ينشئ إلا ما هو مفقود ولا يحدّث إلا ما تغيّر فعلًا.

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

بعد ذلك

مرجع
CLI
كل أمر وخيار ومتطلب مفتاح mcp:*.
دليل
المفاتيح المُسطّحة أو المتداخلة
منع المفاتيح ذات النقاط من الانكسار بعد الاستيراد.
دليل
تحديث القيمة المصدر
تغيير النص المصدر لمفتاح بعد إنشائه.