@intlayer/docs 9.1.3 → 9.3.0

package/dist/types/generated/legal.entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legal.entry.d.ts","names":[],"sources":["../../../src/generated/legal.entry.ts"],"mappings":";;cAsDa;WACX,gCAmBgB,OAAO,eAAe;WACtC,kCAmBgB,OAAO,eAAe"}
+{"version":3,"file":"legal.entry.d.ts","names":[],"sources":["../../../src/generated/legal.entry.ts"],"mappings":";;cAsFa;WACX,gCAmBgB,OAAO,eAAe;WACtC,kCAmBgB,OAAO,eAAe"}

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/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: تحسين حجم وأداء حزمة i18n
 description: قم بتقليل حجم حزمة تطبيقك عن طريق تحسين محتوى التدويل (i18n). تعلم كيفية الاستفادة من "tree shaking" والتحميل الكسول (lazy loading) للقواميس مع Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` و`minify` تعمل الآن على Next.js عبر `@intlayer/swc` — لا حاجة إلى `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "سرد إضافات Babel بالترتيب المطلوب لخط المعالجة (extract → purge → minify → optimize) في الجداول المرجعية"
   - version: 8.12.0
     date: 2026-06-07
     changes: "تمت إضافة `intlayerPurgeBabelPlugin` و `intlayerMinifyBabelPlugin` لـ Babel/Webpack؛ توضيح مسار الإضافات (plugin pipeline)"
@@ -191,12 +197,14 @@ export default {
 
 تُستخدم هذه مباشرة في `babel.config.js` للإعدادات المستندة إلى Webpack (مثل Next.js مع Babel، CRA، Webpack المخصص، إلخ).
 
+يسرد الجدول أدناه هذه الإضافات بالترتيب المطلوب لخط المعالجة (وهو الترتيب نفسه الذي يجب أن تظهر به في `babel.config.js`):
+
 | الإضافة                       | ما تفعله                                                                                                             |
 | :---------------------------- | :------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | تمسح ملفات `.content.ts` وتكتب القواميس المجمعة إلى `.intlayer/`                                                     |
-| `intlayerOptimizeBabelPlugin` | تعيد كتابة `useIntlayer('key')` → `useDictionary(hash)` وتحقن الـ `import` المطابق للقاموس                           |
 | `intlayerPurgeBabelPlugin`    | تمسح جميع ملفات المصدر، تزيل **حقول المحتوى غير المستخدمة** من ملفات القاموس المجمعة `.intlayer/**/*.json`           |
 | `intlayerMinifyBabelPlugin`   | **تعيد تسمية مفاتيح حقول المحتوى** إلى أسماء مستعارة أبجدية قصيرة (`title` → `a`) في كل من ملفات JSON والكود المصدري |
+| `intlayerOptimizeBabelPlugin` | تعيد كتابة `useIntlayer('key')` → `useDictionary(hash)` وتحقن الـ `import` المطابق للقاموس                           |
 
 > **ترتيب الإضافات مهم.** في `babel.config.js` يجب أن تظهر إضافات التطهير (purge) والتصغير (minify) **قبل** إضافة التحسين (optimize). تقوم خطوة التحسين باستبدال `useIntlayer('key')` باستدعاء مبهم لـ `useDictionary(hash)`، مما يمحو معلومات مفتاح القاموس التي تحتاجها خطوات التطهير والتصغير لتحديد الحقول المستخدمة.
 
@@ -205,9 +213,9 @@ export default {
 | مساعد الخيارات (Options helper) | يُستخدم مع                    |
 | :------------------------------ | :---------------------------- |
 | `getExtractPluginOptions()`     | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()`    | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`       | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`      | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()`    | `intlayerOptimizeBabelPlugin` |
 
 ### إضافات Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ export default {
 | Dictionary minify   | نفس مسار كتابة JSON في `intlayerMinifyBabelPlugin`                                             |
 | Babel transform     | نفس مسار إعادة تسمية كود المصدر لـ `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
+### إضافة SWC (`@intlayer/swc`)
+
+مستخدمو Next.js أيضًا **لا يهيئون هذه الإضافات مباشرةً أبدًا**. منذ الإصدار **v9.2.1**، تشغّل `withIntlayer()` في `next.config.ts` خط المعالجة الكامل — التنقية والتصغير وإعادة كتابة عمليات الاستيراد — اعتمادًا على العَلَمين `build.purge` و`build.minify` فقط.
+
+العمل مقسوم إلى نصفين، لأن إضافة SWC بصيغة Wasm تحوّل ملفًا واحدًا في كل مرة ولا تملك وصولًا إلى نظام الملفات:
+
+| المرحلة                                      | أين تُنفَّذ                 | ماذا تفعل                                                                                |
+| :------------------------------------------- | :-------------------------- | :--------------------------------------------------------------------------------------- |
+| تحليل الاستخدام + تنقية/تصغير JSON           | Node، داخل `withIntlayer()` | تقرأ كل ملف مصدر للمكوّنات، وتعيد كتابة `.intlayer/**/*.json`، وتنتج جداول إعادة التسمية |
+| إعادة كتابة المصدر (`content.title` ← `.a`)  | `@intlayer/swc` (Wasm)      | تطبّق جداول إعادة التسمية على عمليات الوصول إلى الخصائص المقابلة في شيفرتك               |
+| إعادة كتابة الاستيراد (`useIntlayer` ← dict) | `@intlayer/swc` (Wasm)      | مثل `intlayerOptimizeBabelPlugin`                                                        |
+
+إن تحديد _أي_ الحقول غير مستخدمة و_أي_ اسم مستعار يحصل عليه كل حقل يتطلب حالة عابرة للملفات وعمليات إدخال/إخراج على الملفات، لذلك يعمل ذلك النصف داخل Node؛ ولا تتلقى إضافة SWC سوى الجداول الناتجة.
+
 ## الإعداد حسب المنصة
 
 <Tabs>
@@ -227,10 +249,12 @@ export default {
 
 ### Next.js
 
-يتطلب Next.js إضافة `@intlayer/swc` لخطوة التحسين (إعادة كتابة الاستيراد)، لأن Next.js يستخدم SWC للبناء.
+يتطلب Next.js إضافة `@intlayer/swc`، لأن Next.js يستخدم SWC في عمليات البناء. منذ الإصدار **v9.2.1**، تغطي هذه الحزمة الواحدة خط المعالجة بأكمله — التحسين (إعادة كتابة الاستيراد) والتنقية والتصغير.
 
 > لا يتم تثبيت هذا المكون الإضافي افتراضيًا لأن مكونات SWC لا تزال تجريبية لـ Next.js. قد يتغير هذا في المستقبل.
 
+> **Next.js 16.1.0 هو الحد الأدنى للإصدار.** فهو أول إصدار مبني على واجهة ABI لإضافات Wasm المتوافقة مستقبليًا في SWC؛ أما الإصدارات الأقدم فترفض الإضافة. تقرأ `withIntlayer` إصدار Next.js في مشروعك ولا تسجّل الإضافة إطلاقًا دون 16.1.0 — وتظل تلك البناءات ناجحة، غير أنها تعمل من دون تحسين الحزمة.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 بمجرد التثبيت، سيكتشف Intlayer ويستخدم الإضافة تلقائيًا.
 
-بالنسبة لخطوات **التطهير (purge) والتصغير (minify)** (إزالة الحقول وإعادة تسميتها)، قم بتثبيت `@intlayer/babel` بجانبه وأضف إضافات Babel. نظرًا لأن Next.js يستخدم SWC للتحويل ولكنه لا يزال يقيّم `babel.config.js` لإعدادات الإضافات، يتم تشغيل إضافات Babel كخطوة مسبقة قبل SWC.
+لا تحتاج مرحلتا **التنقية والتصغير** (إزالة الحقول وإعادة تسميتها) إلى أي حزمة إضافية ولا إلى `babel.config.js`. غلّف إعداداتك بـ `withIntlayer` وفعّل العَلَمين في `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* إعداداتك */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: يزيل حقول المحتوى غير المستخدمة من .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: يعيد تسمية مفاتيح حقول المحتوى في ملف JSON + الكود المصدري
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // ملاحظة: intlayerOptimizeBabelPlugin غير مطلوب هنا لأن
-    // @intlayer/swc يتعامل مع إعادة كتابة useIntlayer → useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // يزيل حقول المحتوى غير المستخدمة من JSON المضمّن في الحزمة
+    minify: true, // يعيد تسمية مفاتيح حقول المحتوى إلى أسماء مستعارة قصيرة
+  },
 };
+
+export default config;
 ```
 
+أثناء `next build`، تحلّل `withIntlayer` مصادرك، وتعيد كتابة القواميس المُجمَّعة، ثم تمرّر جداول إعادة تسمية الحقول الناتجة إلى `@intlayer/swc`، التي تحدّث عمليات الوصول إلى الخصائص المقابلة في شيفرتك.
+
+> استخدم `withIntlayer` غير المتزامنة، لا `withIntlayerSync`. فالنسخة المتزامنة لا تشغّل خط معالجة التحليل، ولذلك لا أثر للتنقية والتصغير معها.
+
+> تعمل التنقية والتصغير عند `next build` فقط — إذ يكون خط معالجة التحسين متوقفًا أثناء `next dev`.
+
+> كما تتعطلان عند تهيئة مستدعِيات محوّلات التوافق (`swcExtraCallers`، التي تضبطها حزم التوافق مثل `@intlayer/next-intl` أو `@intlayer/react-i18next`): فمواضع الاستدعاء تلك غير مرئية لمحلّل الاستخدام، ومن ثم فإن التنقية ستزيل حقولًا لا تزال الشيفرة تقرؤها. أما إعادة كتابة الاستيراد فتبقى فعّالة.
+
+**كانت الإصدارات الأقدم (قبل 9.2.1)** تتطلب `@intlayer/babel` وملف `babel.config.js` يعلن `intlayerPurgeBabelPlugin` و`intlayerMinifyBabelPlugin`. لم يعد ذلك الملف ضروريًا ويمكن حذفه.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > يتم تخطي التصغير عندما يكون `optimize` في وضع `false` أو عندما يكون `editor.enabled` في وضع `true` (يحتاج المحرر المرئي إلى أسماء الحقول الأصلية للسماح بالتحرير).
 
+> في Next.js، يُتخطى التصغير أيضًا عندما لا تكون `@intlayer/swc` مثبّتة أو يتعذر تحميلها (إصدار Next.js أقل من 16.1.0). فالإضافة هي النصف الذي يعيد كتابة عمليات الوصول في المصدر، ومن ثم فإن إعادة تسمية القواميس من دونها ستترك شيفرتك تقرأ أسماء حقول لم تعد موجودة.
+
 > يتم أيضًا تخطي التصغير بالنسبة للقواميس التي تم تحميلها عبر `importMode: 'fetch'` لأن ملف JSON الخاص بهم يُقدّم من واجهة برمجة تطبيقات (API) بعيدة باستخدام أسماء الحقول الأصلية — سيؤدي تغيير أسماء المفاتيح من جانب العميل إلى كسر العقد بين الخادم/العميل.
 
 ### التطهير (إزالة الحقول غير المستخدمة)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> يتم تخطي التطهير (Purge) عندما يكون `optimize` في وضع `false` أو عندما يكون `editor.enabled` في وضع `true`.
+> يتم تخطي التطهير (Purge) عندما يكون `optimize` في وضع `false` أو عندما يكون `editor.enabled` في وضع `true`. وفي Next.js تُتخطى كذلك عندما تكون `@intlayer/swc` غير متاحة، وعند تهيئة مستدعِيات محوّلات التوافق.
 
 > يتم أيضًا تخطي التطهير كإجراء احترازي عندما يتعذر تحليل ملف المصدر، أو عندما يتم تعيين نتيجة `useIntlayer` لمتغير ويتم تمريرها بطرق لا يستطيع المحلل الثابت تتبعها (مثل وضعها في كائن بطريقة النشر، تمريرها كخاصية بدون تفكيك الهيكل). في تلك الحالات، يتم الاحتفاظ بالقاموس بالكامل.
 

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.
 
 ## كيف يعمل تضمين الملفات