REST API
React + i18next
سيُولَّد مرجع API الكامل تلقائياً من مواصفات OpenAPI 3.1 الخاصة بنا في اللحظة التي تستقر فيها الواجهة. نُفضّل شحن صفحة placeholder بدلاً من توثيق وهمي لنقاط نهاية قد تتغير. في هذه الأثناء، إليك الشكل، وما سيغطّيه، وما يمكنك فعله اليوم.
التثبيت
يتطلب <strong>Node 20 LTS</strong> أو أحدث. يُثبَّت ملفّان تنفيذيان: <code>verbumia</code> والاسم المختصر <code>vrb</code> — يمكن تبادلهما.
terminal 1npm i @verbumia/react-i18next2. لفّ تطبيقك
يأخذ VerbumiaProvider قيمتي projectId وapiKey. كل ما عداهما يأتي بإعدادات افتراضية معقولة: اكتشاف اللغة تلقائياً من المتصفح، تحميل namespaces بشكل كسول من CDN، ومعالج للمفاتيح الناقصة مع debounce وإرسال POST تلقائي.
main.tsx 1// src/main.tsx2import { VerbumiaProvider } from "@verbumia/react-i18next";3import { createRoot } from "react-dom/client";4import { App } from "./App"; 6createRoot(document.getElementById("root")!).render(7 <VerbumiaProvider8 projectId="proj_xxx"9 apiKey={import.meta.env.VITE_VERBUMIA_KEY}10 defaultLocale="en"11 namespaces={["common"]}12 >13 <App />14 </VerbumiaProvider>15); كل props الخاصة بـ VerbumiaProvider
| Prop | النوع | القيمة الافتراضية |
|---|---|---|
| projectId | string | — مطلوب |
| apiKey | string | — مطلوب |
| defaultLocale | string | browser |
| defaultNS | string | "common" |
| namespaces | string[] | ["common"] |
| cdnUrl | string | cdn.verbumia.ca |
| baseUrl | string | api.verbumia.ca |
| 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 "@verbumia/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.verbumia.caمع تخزين HTTP المؤقت وstale-while-revalidate. لا حاجة لأي تجميع وقت البناء. - اكتشاف اللغة تلقائياً. إذا لم تمرّر
defaultLocale، يقرأ SDK قيمةnavigator.languageويرجع إلى لغة المشروع الافتراضية عند الإخفاق. - تصدير مفتوح. أي شيء ترسله إلى Verbumia يمكن تصديره مجدداً إلى JSON i18next أو XLIFF أو PO. بدّل أداتك غداً دون إعادة كتابة الكود.
نقل مخصص (متقدم)
تحتاج إلى تسجيل المفاتيح الناقصة في منظومة الرصد الخاصة بك، أو حمايتها خلف المصادقة، أو محاكاتها في الاختبارات؟ مرّر دالة transport. يستمر SDK في تنفيذ debounce والتجميع، وأنت تقرر ما يحدث للدفعة.
main.tsx 1// custom transport — useful for tests, edge cases, or auditing2<VerbumiaProvider3 projectId="proj_xxx"4 apiKey={import.meta.env.VITE_VERBUMIA_KEY}5 debounceMs={2000}6 transport={(batch) => fetch("/internal/i18n-misses", {7 method: "POST",8 body: JSON.stringify(batch),9 })}10/>