بداية سريعة
React + i18next
ثبّت SDK، ولفّ تطبيقك بـ <SonentaProvider />، ثم استدعِ useTranslation(). تنتقل المفاتيح الناقصة إلى لوحة التحكم تلقائياً — دون أي توصيلات إضافية.
1. التثبيت
تبعية واحدة فقط. لا حاجة لمعاناة peer-dep — يضم SDK كل ما يلزم على جانب React.
terminal 1npm i @sonenta/react-i18next2. لفّ تطبيقك
يأخذ SonentaProvider قيمتي projectId وapiKey. كل ما عداهما يأتي بإعدادات افتراضية معقولة: اكتشاف اللغة تلقائياً من المتصفح، تحميل namespaces بشكل كسول من CDN، ومعالج للمفاتيح الناقصة مع debounce وإرسال POST تلقائي.
main.tsx 1// src/main.tsx2import { SonentaProvider } from "@sonenta/react-i18next";3import { createRoot } from "react-dom/client";4import { App } from "./App"; 6createRoot(document.getElementById("root")!).render(7 <SonentaProvider8 projectUuid="proj_xxx"9 token={import.meta.env.VITE_SONENTA_TOKEN}10 defaultLocale="en"11 namespaces={["common"]}12 >13 <App />14 </SonentaProvider>15); كل props الخاصة بـ SonentaProvider
| Prop | النوع | القيمة الافتراضية |
|---|---|---|
| projectUuid | string | — مطلوب |
| token | string | — مطلوب |
| defaultLocale | string | browser |
| defaultNS | string | "common" |
| namespaces | string[] | ["common"] |
| cdnUrl | string | cdn.sonenta.com |
| baseUrl | string | api.sonenta.com |
| missingHandlerEndpoint | string | /v1/missing |
| debounceMs | number | 5000 |
| transport | (batch) => void | Promise<void> | internal |
3. استخدم الـ hook
يُعيد useTranslation() الكائن { t, i18n }. شكل مألوف لمن استخدم react-i18next. يخبرك i18n.ready متى اكتمل تحميل الـ namespaces الأولية، ويبدّل i18n.changeLanguage() اللغة في الـ runtime.
Checkout.tsx 1// src/Checkout.tsx2import { useTranslation } from "@sonenta/react-i18next"; 4export function Checkout() {5 const { t, i18n } = useTranslation("common"); 7 if (!i18n.ready) return null; // first paint after hydration 9 return (10 <button onClick={() => i18n.changeLanguage("fr")}>11 {t("checkout.review.confirm")}12 </button>13 );14}ما تحصل عليه مجاناً
- التقاط المفاتيح الناقصة. أي مفتاح تستدعيه وغير موجود في القاموس يُضاف إلى الطابور، يمر بـ debounce (افتراضياً 5 ثوانٍ)، ثم يُرسل POST إلى طابور missing في لوحة التحكم. آمن للإنتاج — يستمر عرض النص الاحتياطي.
- namespaces مُقدَّمة عبر CDN. تُجلب حِزم الترجمة من
cdn.sonenta.comمع تخزين HTTP المؤقت وstale-while-revalidate. لا حاجة لأي تجميع وقت البناء. - اكتشاف اللغة تلقائياً. إذا لم تمرّر
defaultLocale، يقرأ SDK قيمةnavigator.languageويرجع إلى لغة المشروع الافتراضية عند الإخفاق. - تصدير مفتوح. أي شيء ترسله إلى Sonenta يمكن تصديره مجدداً إلى JSON i18next أو XLIFF أو PO. بدّل أداتك غداً دون إعادة كتابة الكود.
نقل مخصص (متقدم)
تحتاج إلى تسجيل المفاتيح الناقصة في منظومة الرصد الخاصة بك، أو حمايتها خلف المصادقة، أو محاكاتها في الاختبارات؟ مرّر دالة transport. يستمر SDK في تنفيذ debounce والتجميع، وأنت تقرر ما يحدث للدفعة.
main.tsx 1// custom transport — useful for tests, edge cases, or auditing2<SonentaProvider3 projectUuid="proj_xxx"4 token={import.meta.env.VITE_SONENTA_TOKEN}5 debounceMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>