@intlayer/docs 9.1.3 → 9.2.0

package/docs/ar/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | تتبع عرض المحتوى وإجراء اختبارات A/B
+description: اكتشف كيف يقوم @intlayer/analytics بتتبع مشاهدات الصفحات/اللغات وعرض المحتوى، وكيفية استخدامه لإجراء اختبارات A/B على محتوى Intlayer الخاص بك.
+keywords:
+  - التحليلات
+  - اختبار A/B
+  - الجمهور
+  - التدويل (Internationalization)
+  - التوثيق
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — @intlayer/analytics package, provider/node-level tracking, A/B testing, dashboard"
+author: aymericzip
+---
+
+# توثيق Intlayer Analytics
+
+`@intlayer/analytics` هي حزمة مساعدة اختيارية تخبرك **بالمحتوى الذي يتم عرضه بالفعل** لزوارك — أي صفحة، بأي لغة (locale)، وأي جزء محدد من المحتوى المترجم — حتى تتمكن من فهم جمهورك وإجراء **اختبارات A/B على المحتوى**.
+
+## جدول المحتويات
+
+<TOC/>
+
+---
+
+## ما الذي يتم تتبعه
+
+تجمع حزمة `@intlayer/analytics` ثلاثة أنواع من الأحداث المجهولة في دفعات:
+
+| الحدث (Event)      | أين يتم التقاطه                                  | ماذا يخبرك                                                                                                 |
+| ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `page_view`        | على مستوى المزود (`IntlayerProvider`)            | أي صفحة ولغة شاهدتها الجلسة، عند التحميل الأولي، أو تغيير المسار، أو تبديل اللغة.                          |
+| `content_exposure` | على مستوى العقدة (`useIntlayer` / إضافات المفسر) | أي مفتاح قاموس / مسار مفتاح تم حله وعرضه بالفعل — وإذا كان جزءًا من تجربة، أي **متغير (variant)** تم عرضه. |
+| `conversion`       | أينما تستدعي `useConversion()`                   | هدف تم تحقيقه (تسجيل، نقرة، شراء...) يُنسب إلى متغير A/B الذي تعرضت له الجلسة.                             |
+
+يتم جمع الأحداث في الذاكرة وإرسالها كـ **طلب دفعة واحد كل 20 ثانية تقريبًا** — وليس عند كل ضغطة زر أو كل عملية تصيير (render) — لذا فإن التحليلات لا تؤثر أبدًا على وقت التصيير الأول ولا تضيف طلبًا عند كل تفاعل.
+
+## كيف يدعم اختبارات A/B على المحتوى
+
+يسمح لك Intlayer بالفعل بتعريف [متغيرات المحتوى (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md) (على سبيل المثال، قاموس `hero-banner` مع متغير `control` ومتغير `black_friday`). حزمة `@intlayer/analytics` تغلق الدائرة:
+
+1. دالة `getVariant(experimentKey, variants)` تخصص بشكل حتمي كل جلسة مجهولة لمتغير — وهي دالة بحتة تعتمد على معرف الجلسة ومفتاح التجربة، لذا فإن التخصيص يكون **مستقرًا طوال الجلسة** ولا يتطلب **أي اتصال بالخادم (server round-trip)** قبل التصيير الأول (بدون وميض، وبدون تحول في التخطيط).
+2. كل حدث `content_exposure` يحمل الـ `variant` الذي تم عرضه.
+3. تتيح لك `useConversion()` نسبة هدف (مثل `"cta_click"`) إلى ذلك المتغير.
+4. تقارن نقطة نهاية (endpoint) نتائج التجربة في لوحة التحكم معدلات التحويل لكل متغير، بما في ذلك الدلالة الإحصائية (اختبار z).
+
+## التثبيت
+
+حزمة `@intlayer/analytics` هي **تبعية نظيرة واختيارية (peer, optional)** — لا يتم تثبيتها تلقائيًا أبدًا بواسطة حزم إطارات العمل. أضفها جنبًا إلى جنب مع `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+إذا لم تقم بتثبيتها، فإن كل نقطة تكامل تتحول إلى عملية لا تفعل شيئًا (no-op) — انظر [تكلفة صفرية عند عدم التثبيت](#تكلفة-صفرية-عند-عدم-التثبيت) أدناه.
+
+## التكوين (Configuration)
+
+التحليلات **تعيد استخدام كتلة التكوين `editor` الحالية** — لا يوجد مخطط تكوين `analytics` منفصل لملئه:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // يستخدم أيضًا كنقطة نهاية لاستيعاب أحداث التحليلات
+    clientId: "your-client-id", // يستخدم أيضًا كمفتاح مشروع التحليلات
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — عنوان URL الأساسي الذي يتم إرسال أحداث التحليلات إليه (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — مفتاح المشروع العام المنسوب إلى كل حدث يتم استيعابه. وهو يعمل أيضًا كـ **مفتاح تفعيل**: تظل التحليلات معطلة تمامًا (ومحذوفة كتعليمات برمجية ميتة، انظر أدناه) حتى يتم تكوين `clientId`.
+
+إذا قمت بالاستضافة الذاتية لـ Intlayer (self-host)، فإن التحليلات تشير تلقائيًا إلى النسخة الخاصة بك لأنها تتشارك `editor.backendURL`.
+
+## دعم إطارات العمل
+
+التحليلات مدمجة في `IntlayerProvider` المشترك من `react-intlayer`، لذا فهي متاحة اليوم في أي مكان يُستخدم فيه هذا المزود:
+
+| إطار العمل (Framework)                                   | الحالة (Status)                                                                      |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| React                                                    | ✅ متاح                                                                              |
+| Next.js (`next-intlayer`)                                | ✅ متاح (عبر `react-intlayer`)                                                       |
+| React Native / Expo (`react-native-intlayer`)            | ✅ متاح (عبر `react-intlayer`)                                                       |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 مخطط له — نفس العميل، ارتباطات على مستوى المزود تتبع نمط إطلاق `@intlayer/editor` |
+
+## الاستخدام
+
+### التتبع التلقائي على مستوى المزود
+
+لا توجد تغييرات برمجية مطلوبة. بمجرد تثبيت `@intlayer/analytics` وتكوين `editor.clientId`، يقوم `IntlayerProvider` تلقائيًا بـ:
+
+- تهيئة عميل التحليلات عند التحميل (mount)،
+- تسجيل `page_view` عند التحميل الأولي،
+- تسجيل `page_view` عند كل تغيير في اللغة (locale)،
+- بدء حلقة الإرسال كل ~20 ثانية وإرسال أي أحداث متبقية عند إزالة التحميل / إغلاق التبويب (عبر `navigator.sendBeacon`، مع العودة إلى `fetch(..., { keepalive: true })`).
+
+### التتبع التلقائي على مستوى العقدة (Node)
+
+في كل مرة يقوم فيها `useIntlayer` بحل جزء من المحتوى لعرضه، يقوم المفسر بالإبلاغ عن حدث `content_exposure` لذلك الـ `dictionaryKey` المحدد + مسار المفتاح + اللغة — مرة أخرى، لا توجد تغييرات برمجية مطلوبة. يتم تجميع مرات العرض المتكررة لنفس العقدة داخل نافذة الإرسال في حدث واحد مع `count` (عدد)، لذلك فإن القائمة التي تتم إعادة تصييرها 50 مرة لا ترسل 50 حدثًا.
+
+### تتبع التحويلات (Conversions) لاختبارات A/B
+
+استخدم `useConversion()` لنسبة هدف إلى المتغير الذي شاهدته الجلسة:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      ابدأ الآن
+    </button>
+  );
+};
+```
+
+### حل متغير على جانب العميل
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## الخصوصية والأداء
+
+- **مجهول حسب التصميم**: يتم تحديد الجلسات بواسطة معرّف متغير (rotating id)؛ وتقوم الواجهة الخلفية (backend) دائمًا بتخزين **تجزئة SHA-256** فقط لهذا المعرف — ولا تقوم أبدًا بتخزين المعرف الخام، ولا تقوم أبدًا بتخزين عنوان IP.
+- **الموقع تقريبي**: فقط رمز الدولة، المستمد من رؤوس تحديد الموقع الجغرافي الخاصة بشبكة CDN (مثل `cf-ipcountry`، `x-vercel-ip-country`، ...) — لا يتم قراءة أو تخزين أي IP.
+- **تستبعد عناوين URL معلمات البحث** افتراضيًا، لذلك لا يتم التقاط سلاسل الاستعلام (query strings) أبدًا.
+- **أخذ العينات (Sampling)**: يتيح لك `sampleRate` الاحتفاظ بجزء بسيط فقط من أحداث عرض المحتوى في التطبيقات ذات حركة المرور العالية.
+- **معالجة مجمعة (Batched)**: طلب واحد تقريبًا كل 20 ثانية (`flushInterval`)، أو في وقت مبكر إذا امتلأت الذاكرة المؤقتة (`maxBufferSize`) — لا يتم أبدًا إرسال طلب واحد لكل حدث.
+
+### تكلفة صفرية عند عدم التثبيت
+
+تتبع `@intlayer/analytics` نفس نمط التبعية الاختيارية المتبع في `@intlayer/editor`:
+
+- تقوم كل نقطة تكامل بتحميل الحزمة عبر **استيراد ديناميكي `import()` مغلف بـ `try/catch`** — التطبيق الذي لم يقم أبدًا بتثبيت `@intlayer/analytics` لا يدفع أي تكلفة لحجم الحزمة أو وقت التشغيل، ولا يرى خطأ أبدًا؛
+- متغير البيئة في وقت التجميع (`INTLAYER_ANALYTICS_ENABLED`)، والذي يتم تعيينه تلقائيًا إلى `'false'` بواسطة `@intlayer/config` كلما لم يتم تكوين `editor.clientId`، يسمح للمجمعين (bundlers) بـ **إزالة التعليمات البرمجية الميتة (dead-code-eliminate)** للتكامل بأكمله؛
+- يتم تعطيل التحليلات داخل نافذة إطار المعاينة (iframe) الخاصة بمحرر Intlayer / CMS، لذا لا يتم حساب جلسات المحرر كحركة مرور حقيقية أبدًا.
+
+## لوحة التحكم (Dashboard): صفحة التحليلات
+
+بمجرد أن يجمع مشروعك الأحداث، فإن صفحة **التحليلات (Analytics)** في [لوحة تحكم Intlayer](https://app.intlayer.org/analytics) (تظهر في الشريط الجانبي بمجرد تحديد المشروع) تعرض:
+
+- **المستخدمين النشطين** — الزوار الفريدين خلال النافذة الزمنية المحددة (7 / 30 / 90 يومًا).
+- **المستخدمين اليوم** و **المستخدمين خلال آخر 7 أيام**.
+- **مشاهدات الصفحة** خلال النافذة المحددة.
+- **رسم بياني للتطور** للزوار الفريدين اليوميين.
+- علامات تبويب لتحليل **اللغات (Locales)** و **الموقع (Location)**، مما يصنف جمهورك حسب اللغة وحسب البلد.
+
+## مرجع واجهة برمجة تطبيقات الواجهة الخلفية (Backend API)
+
+تتطلب جميع نقاط نهاية القراءة المصادقة؛ استيعاب البيانات عام وينسب إلى `clientId`.
+
+| الطريقة (Method) | نقطة النهاية (Endpoint)                     | الوصف (Description)                                                    |
+| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
+| `POST`           | `/api/analytics/events`                     | استيعاب دفعة من الأحداث (عام، يُنسب بواسطة `clientId` في جسم الطلب).   |
+| `GET`            | `/api/analytics/overview`                   | إجماليات الصفحة/اللغة للمشروع الموثق.                                  |
+| `GET`            | `/api/analytics/audience?days=30`           | زوار فريدون، مشاهدات الصفحة، سلاسل يومية، تفصيلات اللغة + البلد.       |
+| `GET`            | `/api/analytics/content-stats`              | إجماليات عرض كل محتوى، مجمعة حسب مفتاح القاموس / مسار المفتاح / اللغة. |
+| `GET`            | `/api/analytics/experiments/:experimentKey` | معدلات التحويل لكل متغير والدلالة الإحصائية لتجربة A/B.                |
+
+يمكنك أيضًا استدعاء هذه النقاط برمجيًا باستخدام [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## روابط مفيدة
+
+- [القواميس الديناميكية - المجموعات والمتغيرات](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md)
+- [محرر Intlayer المرئي](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_visual_editor.md)
+- [مرجع التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md)
+- [دليل الاستضافة الذاتية (Self-Hosting)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/self_hosting.md)

package/docs/ar/autoFill.md

@@ -75,11 +75,30 @@ author: aymericzip
 
 عند استخدام خيار المسار للكتابة إلى ملف آخر، تعمل آلية الملء من خلال علاقة _master-slave_ بين ملفات إعلان المحتوى. يعمل الملف الرئيسي (master) كمصدر الحقيقة، وعند تحديثه، سيقوم Intlayer تلقائياً بتطبيق تلك التغييرات على ملفات إعلان المحتوى المشتقة (المملوءة) المحددة بواسطة المسار.
 
-# ترجمات ملف إعلان محتوى التعبئة التلقائية
+### تخصيص لكل Locale
 
-**ملفات إعلان محتوى التعبئة التلقائية** هي وسيلة لتسريع سير عمل التطوير الخاص بك.
+يمكنك أيضًا تخصيص السلوك لكل locale باستخدام كائن:
 
-تعمل آلية التعبئة التلقائية من خلال علاقة _رئيسي-تابع_ بين ملفات إعلان المحتوى. عندما يتم تحديث الملف الرئيسي (الرئيسي)، يقوم Intlayer تلقائيًا بتطبيق تلك التغييرات على ملفات الإعلان المشتقة (المعبأة تلقائيًا).
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // يُنصح به لتجنب Property 'pl' is missing in type '{ en: string; xxx } على دالة t الخاصة بك إذا
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // ملء وتعديل الملف الحالي للغة الإنجليزية
+      fr: "./translations/fr.json", // إنشاء ملف منفصل للفرنسية
+      es: false, // تعطيل الملء للإسبانية
+    },
+  },
+};
+```
+
+هذا يسمح لك بوجود سلوكيات ملء مختلفة لـ locales مختلفة ضمن نفس المشروع.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,18 +106,18 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
-    contentExample: "هذا مثال على المحتوى",
+    contentExample: "This is an example of content",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-إليك [ملف إعلان محتوى لكل لغة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/per_locale_file.md) يستخدم تعليمة `autoFill`.
+إليك [ملف إعلان المحتوى لكل locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/per_locale_file.md) باستخدام تعليمات `fill`.
 
-ثم، عند تشغيل الأمر التالي:
+بعد ذلك، عند تشغيل الأمر التالي:
 
 ```bash packageManager="npm"
 npx intlayer fill --file 'src/components/example/example.content.ts'
@@ -116,7 +135,7 @@ pnpm intlayer fill --file 'src/components/example/example.content.ts'
 bun x intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-سيقوم Intlayer تلقائيًا بإنشاء ملف الإعلان المشتق في `src/components/example/example.content.json`، مع ملء جميع اللغات التي لم تُعلن بعد في الملف الرئيسي.
+سيقوم Intlayer تلقائيًا بإنشاء ملف الإعلان المشتق في `src/components/example/example.content.json`، وملء جميع locales التي لم يتم إعلانها بالفعل في الملف الرئيسي.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -133,7 +152,7 @@ bun x intlayer fill --file 'src/components/example/example.content.ts'
 }
 ```
 
-بعد ذلك، سيتم دمج كلا ملفي الإعلان في قاموس واحد، يمكن الوصول إليه باستخدام الخطاف القياسي `useIntlayer("example")` (react) / القابل للاستخدام (vue).
+بعد ذلك، سيتم دمج ملفات الإعلان معًا في قاموس واحد، يمكن الوصول إليه باستخدام hook `useIntlayer("example")` القياسي (react) / composable (vue).
 
 ## الإعدادات العامة
 

package/docs/ar/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: الإعدادات (Configuration)
 description: تعرف على كيفية إعداد Intlayer لتطبيقك. افهم الإعدادات والخيارات المختلفة المتاحة لتخصيص Intlayer وفقًا لاحتياجاتك.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "جعل `routing.enableProxy` ثلاثي الحالات: غير محدد (auto)، `true`، `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "إضافة إعدادات `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * يفعّل وكيل توجيه اللغات في Intlayer (البرمجية الوسيطة).
+     * يتولى اكتشاف اللغة وإعادة التوجيه وإعادة الكتابة في dev وpreview وSSR.
+     * - غير محدد (auto): تُبقي خوادم dev وpreview التوجيه معتمدًا على الرابط،
+     *   متجاهلةً اللغة المخزّنة في ملفات تعريف الارتباط والترويسات. تظل البادئات
+     *   تُحلّ، وتظل اللغة تُحفظ، ويظل اكتشاف Accept-Language ساريًا.
+     *   في الإنتاج يتصرف مثل `true`.
+     * - true: السلوك الكامل في جميع البيئات.
+     * - false: بدون توجيه للغات.
+     * الافتراضي: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * أين يتم تخزين اللغة التي يختارها المستخدم.
      * الخيارات: 'cookie' أو 'localStorage' أو 'sessionStorage' أو 'header' أو مصفوفة منها.
@@ -706,13 +722,14 @@ export default config;
 
 الإعدادات التي تتحكم في سلوك التوجيه، بما في ذلك بنية رابط URL، وتخزين اللغة، وإدارة البرمجيات الوسيطة.
 
-| الحقل      | الوصف                                                                                                                                                                  | النوع                                                                                                                                                                                                        | الافتراضي              | مثال                                                                                                                                                                                                   | ملاحظة                                                                                                                                                                                                                                                                           |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | وضع توجيه رابط URL لإدارة اللغات.                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (الإنجليزية) أو `/fr/dashboard` (الفرنسية). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: تتم إدارة اللغة بوسائل أخرى. `'search-params'`: `/dashboard?locale=fr` | لا يؤثر على إدارة الكوكيز أو تخزين اللغات.                                                                                                                                                                                                                                       |
-| `storage`  | إعدادات تخزين اللغة على العميل.                                                                                                                                        | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                                     | انظر جدول معالم التخزين أدناه.                                                                                                                                                                                                                                                   |
-| `basePath` | المسار الأساسي لروابط التطبيق.                                                                                                                                         | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                            | إذا كان التطبيق يعمل على العنوان `https://example.com/my-app` ، فإن الـ basePath هو `'/my-app'` وتصبح الروابط `https://example.com/my-app/en`.                                                                                                                                   |
-| `rewrite`  | قواعد إعادة كتابة رابط URL مخصصة تتجاوز وضع التوجيه الافتراضي لمسارات معينة. تدعم المعاملات الديناميكية `[param]`.                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | انظر المثال أدناه                                                                                                                                                                                      | • لقواعد إعادة الكتابة أولوية على `mode`. <br/> • يعمل مع Next.js و Vite. <br/> • تقوم `getLocalizedUrl()` بتطبيق القواعد المناسبة تلقائياً. <br/> • انظر [إعادة كتابة روابط URL المخصصة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | يربط اللغات بأسماء نطاقات الاستضافة للتوجيه القائم على النطاق. عند تعيينه، تستخدم روابط URL للغة ذلك النطاق كقاعدة (رابط URL مطلق) ولا يتم إضافة بادئة لغة إلى المسار. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                            | • البروتوكول الافتراضي هو `https://` عندما لا يتم تضمينه في اسم الاستضافة.<br/>• النطاق نفسه يحدد اللغة، لذا لا يتم إضافة بادئة `/zh/`.<br/>• `getLocalizedUrl('/', 'zh')` يرجع `https://intlayer.zh/`.                                                                          |
+| الحقل         | الوصف                                                                                                                                                                  | النوع                                                                                                                                                                                                        | الافتراضي              | مثال                                                                                                                                                                                                   | ملاحظة                                                                                                                                                                                                                                                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mode`        | وضع توجيه رابط URL لإدارة اللغات.                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (الإنجليزية) أو `/fr/dashboard` (الفرنسية). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: تتم إدارة اللغة بوسائل أخرى. `'search-params'`: `/dashboard?locale=fr` | لا يؤثر على إدارة الكوكيز أو تخزين اللغات.                                                                                                                                                                                                                                                                                                 |
+| `enableProxy` | يفعّل وكيل توجيه اللغات في Intlayer (البرمجية الوسيطة).                                                                                                                | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                                 | • غير محدد (auto): تتجاهل خوادم dev وpreview اللغة المخزّنة في ملفات تعريف الارتباط/الترويسات كمصدر لإعادة التوجيه؛ وتظل البادئات والحفظ واكتشاف `Accept-Language` سارية. في الإنتاج يتصرف مثل `true`.<br/>• `true`: السلوك الكامل في كل مكان.<br/>• `false`: بدون توجيه للغات. في Next.js تصبح البرمجية الوسيطة `intlayerProxy` مجرد ممر. |
+| `storage`     | إعدادات تخزين اللغة على العميل.                                                                                                                                        | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                                     | انظر جدول معالم التخزين أدناه.                                                                                                                                                                                                                                                                                                             |
+| `basePath`    | المسار الأساسي لروابط التطبيق.                                                                                                                                         | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                            | إذا كان التطبيق يعمل على العنوان `https://example.com/my-app` ، فإن الـ basePath هو `'/my-app'` وتصبح الروابط `https://example.com/my-app/en`.                                                                                                                                                                                             |
+| `rewrite`     | قواعد إعادة كتابة رابط URL مخصصة تتجاوز وضع التوجيه الافتراضي لمسارات معينة. تدعم المعاملات الديناميكية `[param]`.                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | انظر المثال أدناه                                                                                                                                                                                      | • لقواعد إعادة الكتابة أولوية على `mode`. <br/> • يعمل مع Next.js و Vite. <br/> • تقوم `getLocalizedUrl()` بتطبيق القواعد المناسبة تلقائياً. <br/> • انظر [إعادة كتابة روابط URL المخصصة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                           |
+| `domains`     | يربط اللغات بأسماء نطاقات الاستضافة للتوجيه القائم على النطاق. عند تعيينه، تستخدم روابط URL للغة ذلك النطاق كقاعدة (رابط URL مطلق) ولا يتم إضافة بادئة لغة إلى المسار. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                            | • البروتوكول الافتراضي هو `https://` عندما لا يتم تضمينه في اسم الاستضافة.<br/>• النطاق نفسه يحدد اللغة، لذا لا يتم إضافة بادئة `/zh/`.<br/>• `getLocalizedUrl('/', 'zh')` يرجع `https://intlayer.zh/`.                                                                                                                                    |
 
 **مثال لـ `rewrite`**:
 

package/docs/ar/dictionary/file.md

@@ -23,7 +23,9 @@ history:
 author: aymericzip
 ---
 
-# محتوى الملف / تضمين الملفات في Intlayer
+# محتوى الملفات / دمج الملفات في Intlayer
+
+في Intlayer، تسمح دالة `file` بدمج محتوى الملفات الخارجية في قاموس. يضمن هذا النهج أن Intlayer يتعرف على ملف المصدر، مما يتيح التكامل السلس مع محرر Intlayer المرئي و CMS.
 
 ## كيف يعمل تضمين الملفات
 

package/docs/ar/dictionary/nesting.md

@@ -64,6 +64,53 @@ export default firstDictionary;
 }
 ```
 
+### الإشارة باستخدام Nest
+
+الآن، قم بإنشاء وحدة محتوى أخرى تستخدم دالة `nest` للإشارة إلى المحتوى أعلاه. يمكنك الإشارة إلى المحتوى بالكامل أو قيمة محددة متداخلة:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // الإشارة إلى القاموس بالكامل:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // الإشارة إلى قيمة متداخلة محددة:
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+كمعامل ثانٍ، يمكنك تحديد المسار إلى قيمة متداخلة داخل هذا المحتوى. عندما لا يتم توفير مسار، يتم إرجاع محتوى القاموس المرجعي بالكامل.
+
 ## إعداد التعشيش
 
 <Tabs group="framework">
@@ -258,36 +305,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## استخدام التعشيش مع React Intlayer
-
-لاستخدام المحتوى المتعشش في مكون React، استخدم الخطاف `useIntlayer` من حزمة `react-intlayer`. يسترجع هذا الخطاف المحتوى الصحيح بناءً على المفتاح المحدد. إليك مثال على كيفية استخدامه:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const NestComponent: FC = () => {
-  const { fullNestedContent, partialNestedContent } = useIntlayer(
-    "key_of_my_second_dictionary"
-  );
-
-  return (
-    <div>
-      <p>
-        Full Nested Content: {JSON.stringify(fullNestedContent)}
-        {/* الإخراج: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Partial Nested Value: {partialNestedContent}
-        {/* الإخراج: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## موارد إضافية
 
 لمزيد من المعلومات التفصيلية حول التكوين والاستخدام، راجع الموارد التالية: