@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.7

package/docs/ar/intlayer_with_vite+vanilla.md

@@ -188,7 +188,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -449,12 +455,15 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // يجب وضعه أولاً
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -586,6 +595,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='مترجم Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 قم بتحديث `vite.config.ts` الخاص بك لتضمين ملحق `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -595,7 +606,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // يضيف ملحق المترجم
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ar/intlayer_with_vite+vue.md

@@ -608,14 +608,17 @@ import LocaleSwitcher from "@components/LocaleSwitcher.vue";
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -940,6 +943,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='مترجم Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/ar/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: توثيق حزمة @intlayer/babel
+description: إضافات Babel لـ Intlayer تُعالج استخراج المحتوى، وتحسين الاستيراد، وتنقية الحقول غير المستخدمة، وتصغير أسماء الحقول أثناء البناء.
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - internationalization
+  - i18n
+  - compiler
+  - optimize
+  - purge
+  - minify
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "توحيد توثيق جميع الصادرات"
+author: aymericzip
+---
+
+# حزمة @intlayer/babel
+
+توفر حزمة `@intlayer/babel` مجموعة من إضافات Babel المتخصصة لـ Intlayer. تُغطي دورة البناء الكاملة: استخراج تصريحات المحتوى، وإعادة كتابة استدعاءات `useIntlayer` / `getIntlayer` إلى استيرادات قواميس مُحسَّنة، وتنقية الحقول غير المستخدمة، وتصغير أسماء الحقول.
+
+## التثبيت
+
+```bash
+npm install @intlayer/babel
+```
+
+## التصديرات
+
+استيراد:
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### الإضافات (Plugins)
+
+| الدالة / الفئة                 | الوصف                                                                                                                                                                           |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`   | إضافة Babel تستخرج المحتوى القابل للترجمة من ملفات المصدر وتُدرج hooks `useIntlayer` / `getIntlayer` تلقائيًا. مُصمَّمة للاستخدام مع Next.js وأدوات البناء المعتمدة على Babel.  |
+| `intlayerOptimizeBabelPlugin`  | إضافة Babel تُحوِّل استدعاءات `useIntlayer` و`getIntlayer` وتُعيد كتابة استيراداتها إلى استيرادات قواميس JSON مُحسَّنة (ثابتة أو ديناميكية أو عبر fetch).                       |
+| `intlayerPurgeBabelPlugin`     | إضافة Babel تُحلِّل ملفات المصدر وتُعيد كتابة ملفات JSON للقواميس المُجمَّعة لحذف الحقول غير المستخدمة (`build.purge`) أو إعادة تسميتها بأسماء مختصرة (`build.minify`).         |
+| `intlayerMinifyBabelPlugin`    | إضافة Babel تُعيد كتابة ملفات المصدر لاستخدام أسماء الحقول المختصرة المُعيَّنة أثناء مرحلة التصغير (مثلاً `content.title` ← `content.a`). تعتمد على `intlayerPurgeBabelPlugin`. |
+| `makeFieldRenameBabelPlugin`   | دالة مُنشِئة (factory) تُنتج إضافة Babel تُعيد تسمية وصولات حقول محتوى القاموس في ملفات المصدر وفق خريطة `dictionaryKeyToFieldRenameMap` الموجودة في `PruneContext`.            |
+| `makeUsageAnalyzerBabelPlugin` | دالة مُنشِئة تُنتج إضافة Babel تُحلِّل استخدام `useIntlayer` / `getIntlayer` في الكود المصدري وتُجمِّع بيانات استخدام الحقول في `PruneContext` المُشترك.                        |
+| `getSharedPruneContext`        | دالة مساعدة تُعيد كائن `PruneContext` المُشترك للمجلد الأساسي المُحدَّد، أو `null` إن لم يُهيَّأ بعد.                                                                           |
+
+---
+
+### دوال إعداد الإضافات
+
+| الدالة                     | الوصف                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | تُحمِّل إعداد Intlayer وتُعيد خيارات `ExtractPluginOptions` جاهزة للاستخدام مع `intlayerExtractBabelPlugin`.                        |
+| `getOptimizePluginOptions` | تُحمِّل إعداد Intlayer والقواميس المُجمَّعة وتُعيد خيارات `OptimizePluginOptions` جاهزة للاستخدام مع `intlayerOptimizeBabelPlugin`. |
+| `getPurgePluginOptions`    | تُحمِّل إعداد Intlayer وتُعيد خيارات `PurgePluginOptions` جاهزة للاستخدام مع `intlayerPurgeBabelPlugin`.                            |
+| `getMinifyPluginOptions`   | تُحمِّل إعداد Intlayer وتُعيد خيارات `MinifyPluginOptions` جاهزة للاستخدام مع `intlayerMinifyBabelPlugin`.                          |
+
+---
+
+### الأنواع
+
+| النوع                   | الوصف                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | وضع المُجمِّع: `'dev'` للتطوير مع دعم HMR أو `'build'` لبناء الإنتاج.                                   |
+| `ExtractPluginOptions`  | خيارات `intlayerExtractBabelPlugin`: قائمة الملفات، الإعداد، callback `onExtract`، وغيرها.              |
+| `ExtractResult`         | نتيجة الاستخراج: مفتاح القاموس، مسار الملف، المحتوى، واللغة.                                            |
+| `OptimizePluginOptions` | خيارات `intlayerOptimizeBabelPlugin`: مسارات القواميس، وضع الاستيراد، خريطة الأوضاع لكل قاموس، إلخ.     |
+| `PurgePluginOptions`    | خيارات `intlayerPurgeBabelPlugin`: المجلد الأساسي، علامات purge/minify/optimize، قائمة ملفات المكوّنات. |
+| `MinifyPluginOptions`   | خيارات `intlayerMinifyBabelPlugin`: المجلد الأساسي، علامات minify/optimize/editorEnabled.               |
+| `PruneContext`          | الحالة المُشتركة بين إضافات التحليل والتنقية: خرائط استخدام الحقول، خرائط إعادة التسمية، إلخ.           |
+| `DictionaryFieldUsage`  | نتيجة استخدام الحقول لقاموس واحد: `Set<string>` أو `'all'` عند تعذُّر التحديد الساكن.                   |
+| `NestedRenameEntry`     | عقدة في شجرة إعادة التسمية: الاسم المختصر `shortName` وخريطة الأبناء `children`.                        |
+| `NestedRenameMap`       | مستوى واحد في شجرة إعادة التسمية: `Map<string, NestedRenameEntry>`.                                     |
+| `CompatCallerConfig`    | إعداد مُحلِّل استخدام مُتوافق لحزم الـ compat-adapter (اسم المُستدعي وخيارات المعالجة).                 |
+| `ScriptBlock`           | كتلة script مستخرجة من ملف SFC (Vue أو Svelte): المحتوى وإزاحتا البداية والنهاية.                       |
+
+---
+
+### الأدوات المساعدة
+
+| الدالة                            | الوصف                                                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | تُحوِّل رقمًا صحيحًا (ابتداءً من الصفر) إلى معرِّف أبجدي مختصر: `0 → 'a'`, `25 → 'z'`, `26 → 'aa'`, إلخ.                         |
+| `buildNestedRenameMapFromContent` | تبني `NestedRenameMap` بصورة مُتكرِّرة من قيمة محتوى قاموس مُجمَّع، مع احترام بنية عقد Intlayer (translation، enumeration، إلخ). |
+| `createPruneContext`              | تُنشئ كائن `PruneContext` فارغًا جديدًا مُهيَّأً بالقيم الافتراضية.                                                              |
+| `extractScriptBlocks`             | تستخرج كتل `<script>` من ملفات SFC (Vue / Svelte) للتحليل اللاحق بـ Babel.                                                       |
+| `BABEL_PARSER_OPTIONS`            | ثابت يُمثِّل خيارات مُحلِّل Babel تُغطي مجموعة الأُطر المدعومة (React/Vue/Svelte/Angular/…).                                     |
+| `INTLAYER_CALLER_NAMES`           | قائمة ثابتة بأسماء المُستدعِيين الأصلية لـ Intlayer: `['useIntlayer', 'getIntlayer']`.                                           |
+
+---
+
+## مثال على الاستخدام
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **ملاحظة:** يجب أن تُدرَج `intlayerPurgeBabelPlugin` **قبل** `intlayerMinifyBabelPlugin`، لأن الأخيرة تقرأ خريطة إعادة التسمية التي تبنيها الأولى. كما يجب أن تسبقهما معًا `intlayerOptimizeBabelPlugin` حتى تتمكّن من رؤية مفاتيح القاموس قبل إعادة كتابة استدعاءات `useIntlayer`.

package/docs/ar/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: توثيق إضافي لـ intlayerCompiler Vite | vite-intlayer
+description: إضافة Vite التي تستخرج إعلانات محتوى Intlayer المضمنة من ملفات المكونات وتكتبها في ملفات JSON للقاموس في وقت البناء/التحويل.
+keywords:
+  - intlayerCompiler
+  - vite
+  - plugin
+  - compiler
+  - content
+  - dictionary
+  - internationalization
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "مدمج في intlayer()؛ بدء التوثيق"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler` هو عبارة عن إضافة لـ Vite يقوم بفحص ملفات المكونات البرمجية بحثًا عن **إعلانات محتوى Intlayer المضمنة** — وهو المحتوى المعرف مباشرة داخل المكون بدلاً من ملف منفصل `.content.ts` — ويكتبها في ملفات قاموس JSON خلال مرحلة التحويل (transform).
+
+> **بدءاً من إطلاق Intlayer v9** يتم تضمين `intlayerCompiler` تلقائيًا داخل الإضافة الأساسية [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayer.md) عندما يكون كل من `compiler.enabled` هو `true` وتحديد مسار المخرجات `compiler.output` في إعدادات Intlayer الخاصة بك. تحتاج فقط إلى تسجيلها بشكل منفصل إذا كنت تريد التحكم الكامل في إعدادات المترجم المحددة.
+
+## الاستخدام
+
+### كجزء من `intlayer()` (موصى به، الإصدار 9+)
+
+قم بتمكين المترجم (compiler) من خلال إعدادات Intlayer الخاصة بك:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // أين يتم كتابة القواميس المستخرجة
+  },
+});
+```
+
+ثم استخدم الإضافة القياسية بدون تسجيل إضافي:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### منفصل (عند الحاجة)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## الخيارات
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| الخيار           | النوع                     | الوصف                                                                           |
+| ---------------- | ------------------------- | ------------------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | تجاوزات إعدادات Intlayer التي يتم تمريرها إلى `getConfiguration()`.             |
+| `compilerConfig` | `Partial<CompilerConfig>` | تجاوزات لقسم الإعدادات الخاص بالمترجم (مثل `enabled` و `output` و `filesList`). |
+
+### مثال
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## كيف يعمل
+
+### مرحلة التحويل (Transform phase)
+
+لكل ملف مصدر يطابق `compiler.filesList` ، تقوم إضافة المترجم بـ:
+
+1. تمرير محتوى الملف عبر دالة `extractContent` من الحزمة `@intlayer/babel`.
+2. استدعاء `onExtract` لكل إعلان يتم العثور عليه، والذي يقوم بكتابة قاموس JSON الناتج إلى `compiler.output`.
+3. إرجاع الكود المصدري المحول مع استبدال الإعلانات المضمنة باستدعاءات قياسية مثل `useIntlayer('key')` / `getIntlayer('key')`.
+
+أنواع الملفات المدعومة: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### تحديث الوحدات الساخن HMR (Hot Module Replacement)
+
+عندما يتم حفظ ملف مكون في وضع التطوير، يقوم المترجم بـ:
+
+1. الكشف عن تغيير الملف عبر خطاف `handleHotUpdate` الخاص بـ Vite.
+2. إعادة استخراج المحتوى من الملف المحدث.
+3. كتابة قاموس JSON المحدث.
+4. تحفيز إعادة تحميل الصفحة بالكامل (`server.ws.send({ type: 'full-reload' })`).
+
+يمنع مؤقت debounce بمقدار 500 مللي ثانية عملية كتابة القاموس نفسها (التي تؤدي أيضًا إلى حدث تغيير الملف) من التسبب في حلقة لا نهائية لإعادة الاستخراج.
+
+### إزالة التكرار (Deduplication)
+
+يستخدم `intlayerCompiler` نفس آلية إزالة التكرار `createPrimaryInstanceGuard` المستخدمة في الإضافات المدمجة الأخرى. عندما يتواجد كل من `intlayer()` (الذي يتضمن المترجم) واستدعاء يدوي لـ `intlayerCompiler()` ، يتم تشغيل المثيل الأول المسجل فقط — ولا يتم كتابة أي قواميس مرتين.

package/docs/ar/packages/vite-intlayer/intlayerMinify.md

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: توثيق إضافة intlayerMinify Vite | vite-intlayer
+description: إضافة لـ Vite تقوم بتصغير ملفات قاموس Intlayer JSON المترجمة وتغيير أسماء حقول المحتوى اختياريًا لتقليل حجم الحزمة.
+keywords:
+  - intlayerMinify
+  - vite
+  - plugin
+  - minify
+  - bundle size
+  - dictionary
+  - internationalization
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "بدء التوثيق"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify` هو عبارة عن إضافة لـ Vite يقوم بتصغير ملفات قاموس JSON المجمعة أثناء عملية البناء للإنتاج. يقوم بإزالة جميع الفراغات غير الضرورية، وعند دمجه مع `intlayerPrune` ، يعيد تسمية حقول المحتوى اختياريًا إلى أسماء مستعارة أبجدية قصيرة (`a` و `b` و `c` ، ...) لتقليل حجم الحزمة (bundle size) بشكل أكبر.
+
+> تم تضمين هذا المكون الإضافي وتهيئته تلقائيًا بالفعل عند استخدامك لـ [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayer.md). تحتاج فقط إلى تسجيله يدويًا إذا كنت تقوم بتركيب مصفوفة الإضافات بنفسك.
+
+## الاستخدام
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## شروط التفعيل
+
+يكون `intlayerMinify` نشطًا **فقط** عندما تكون الشروط الثلاثة التالية صحيحة:
+
+1. أمر Vite هو `build` (وليس `serve` / dev).
+2. إعداد `build.optimize` هو `true` (أو `undefined` ، والذي يتم تعيينه افتراضيًا إلى `true` لعمليات البناء).
+3. إعداد `build.minify` هو `true` في إعدادات Intlayer الخاصة بك.
+
+يتم **إيقاف تفعيله** تلقائيًا عندما يكون `editor.enabled` هو `true` لأن المحرر يحتاج إلى محتوى القاموس الكامل والمقروء بشريًا.
+
+## ما الذي يتم تصغيره
+
+يستهدف الإضافة موقعين من القاموس (كما هو محدد من `intlayer.system`):
+
+- `dictionariesDir` — قواميس ثابتة لجميع اللغات (مثل `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — قواميس ديناميكية لكل لغة
+
+> قواميس وضع الجلب (`fetchDictionariesDir`) **لا** يتم تصغيرها أبدًا لأنها تُقدم من واجهة برمجية (API) بعيدة في وقت التشغيل باستخدام أسماء حقولها الأصلية. إعادة تسمية الحقول ستنشئ عدم تطابق بين استجابة الخادم والوصول إلى الخصائص على جانب العميل.
+
+## تشويه أسماء الحقول (Property minification)
+
+عندما يقوم `intlayerPrune` بتحليل قاعدة الكود وتعبئة الخريطة `pruneContext.dictionaryKeyToFieldRenameMap` ، يقوم `intlayerMinify` أيضًا بإعادة تسمية أسماء حقول المحتوى إلى أسماء مستعارة قصيرة. على سبيل المثال:
+
+```json
+// قبل التشويه
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// بعد التشويه
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+تتم إعادة تسمية عمليات الوصول إلى الخصائص في الملف المصدر المقابل بواسطة مرحلة Babel داخل `intlayerOptimize` ، لذا يظل سلوك وقت التشغيل دون تغيير.
+
+لا يتم إعادة تسمية حقول Intlayer الداخلية (`nodeType` و `translation` وما إلى ذلك) أبدًا.
+
+## قواميس الحالات الخاصة (Edge-cases)
+
+يتم تخطي القواميس المشار إليها في `pruneContext.dictionariesWithEdgeCases` (الشذوذ الهيكلي الذي تم اكتشافه أثناء مرحلة التقليم) تمامًا — لا يتم تصغيرها ولا تشويهها — لتجنب شحن بيانات تالفة.
+
+## المجموعات المؤهلة (المجموعات / المتغيرات / السجلات الفوقية)
+
+بالنسبة للقواميس التي تحتوي على مصفوفة `qualifierTypes` (المجموعات والمتغيرات والسجلات الفوقية) ، يحتفظ المكون الإضافي بمصفوفة `qualifierTypes` وخريطة `meta` الجانبية حرفيًا. يتم تشويه أسماء الحقول الخاصة بمدخلات `content` فقط. لا يتم لمس المفاتيح المركبة (المستخدمة لمطابقة المحدد في وقت التشغيل) أبدًا.

package/docs/ar/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: توثيق إضافة intlayerProxy Vite | vite-intlayer
+description: برنامج وسيط لتوجيه اللغات لخوادم تطوير/معاينة Vite والـ SSR في الإنتاج. يتعامل مع اكتشاف اللغة، وإعادة توجيه عناوين URL، وإعادة الكتابة الداخلية.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - locale
+  - routing
+  - internationalization
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "تم دمج configOptions في كائن خيارات واحد؛ البروكسي مدمج في intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` هو عبارة عن إضافة لـ Vite يقوم بتسجيل برنامج وسيط لتوجيه اللغات لـ **كل بيئة**: خادم التطوير، وخادم المعاينة، والـ SSR للإنتاج (Nitro / TanStack Start).
+
+> **بدءاً من إطلاق Intlayer v9** يتم تضمين `intlayerProxy` تلقائيًا داخل الإضافة الأساسية [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayer.md) وتمكينه افتراضيًا عبر الخيار `routing.enableProxy: true`. تحتاج فقط لتسجيله بشكل منفصل إذا كنت بحاجة لسرعة تحكم ذات مستوى أدنى أو كنت تستخدمه خارج إطار عمل `intlayer()` القياسي.
+
+## الاستخدام
+
+### كجزء من `intlayer()` (موصى به، الإصدار 9+)
+
+قم بتمرير خيارات الـ `proxy` إلى الإضافة الرئيسية بدلاً من تسجيل `intlayerProxy` بشكل منفصل:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### منفصل (عند الحاجة)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## الخيارات
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+جميع الخيارات اختيارية وتُمرر ككائن واحد:
+
+| الخيار          | النوع                               | الوصف                                                                                                                                     |
+| --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | دالة شرطية تستبعد طلبات معينة من توجيه اللغات. أرجع `true` لتخطي طلب ما (مثل مسارات API أو فحوصات الصحة).                                 |
+| `configOptions` | `GetConfigurationOptions`           | تجاوزات إعدادات Intlayer التي يتم تمريرها إلى `getConfiguration()`. استخدم هذا عندما تحتاج إلى قراءة ملف إعدادات محدد أو تجاوز قيم معينة. |
+
+### مثال
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+تنشئ الدالة `createIntlayerProxyHandler` برنامج وسيط Node.js مستقل وغير مرتبط بإطار عمل معين `(req, res, next)` يحتوي على كل منطق توجيه اللغات. يفيد هذا في البيئات التي لا تتوفر فيها واجهة برمجة تطبيقات إضافات Vite (مثل خادم Node.js عادي أو وحدة Nitro مخصصة).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### الـ SSR للإنتاج (TanStack Start / Nitro عبر h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## سلوك التوجيه
+
+يحاكي البرنامج الوسيط منطق التوجيه الخاص بـ برنامج وسيط `next-intlayer` ويدعم جميع أوضاع توجيه Intlayer.
+
+### أوضاع التوجيه
+
+| الوضع           | عنوان URL المرئي في المتصفح | السلوك                                                                                                                            |
+| --------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/ar/about`                 | الافتراضي. بادئة اللغة في عنوان URL. اللغة الافتراضية تعيد التوجيه لعنوان بدون بادئة إلا إذا تم تفعيل `prefix-all`.               |
+| `prefix-all`    | `/en/about` و `/ar/about`   | جميع اللغات — بما في ذلك اللغة الافتراضية — تحتوي دائمًا على بادئة.                                                               |
+| `no-prefix`     | `/about`                    | لا توجد لغة في عنوان URL. يتم تخزين اللغة في ملفات تعريف الارتباط فقط؛ وتحدث عمليات إعادة كتابة العناوين داخليًا.                 |
+| `search-params` | `/about?locale=ar`          | يتم تمرير اللغة كمعامل استعلام (query parameter). يقوم بإعادة التوجيه لإضافة/تحديث المعامل `locale` عندما يكون مفقودًا أو قديمًا. |
+
+### أولوية الاكتشاف
+
+1. بادئة مسار URL (على سبيل المثال `/ar/about` ← `ar`).
+2. قيمة الكوكيز / localStorage (باستخدام `intlayer-locale`).
+3. ترويسة `Accept-Language`.
+4. اللغة الافتراضية `defaultLocale` من ملف الإعدادات.
+
+### التجاوز التلقائي (Automatic bypass)
+
+يقوم البرنامج الوسيط دائمًا بتمرير هذه الطلبات مباشرة دون معالجة اللغة:
+
+- الطلبات المطابقة لدالة التصفية `ignore`.
+- `/node_modules/**`
+- `/@**` – الملفات الداخلية لـ Vite (`@vite/` و `@fs/` و `@id/` إلخ).
+- `/_**` – الملفات الداخلية للخادم (`__vite_ping` و `__manifest` إلخ).
+- الطلبات التي تنتهي مساراتها بامتداد ملف (أصول ثابتة). إذا تواجدت بادئة لغة في مسار أصل ثابت (مثل `/ar/logo.png`)، يتم تجريدها حتى يتمكن الخادم من تقديم الملف بشكل صحيح.
+
+### توجيه النطاقات (Domain routing)
+
+عندما يتم تكوين `routing.domains` في ملف إعدادات Intlayer الخاص بك، يتعامل البرنامج الوسيط مع توجيه اللغات عبر النطاقات المختلفة:
+
+- يتم إعادة توجيه طلب لـ `/zh/about` على النطاق `intlayer.org` إلى `https://intlayer.zh/about` عندما يكون `domains.zh = "intlayer.zh"`.
+- يتم إعادة كتابة طلب لـ `intlayer.zh/about` داخليًا إلى `/zh/about` بحيث يتم تعبئة معلم المسار `[locale]`.
+
+### الحماية من حلقة إعادة التوجيه
+
+يتتبع البرنامج الوسيط عدد مرات إعادة التوجيه لكل زوج `originalUrl → newUrl` داخل نافذة منزلقة مدتها ثانيتان. إعادة توجيه أكثر من 10 مرات في تلك النافذة ترجع استجابة بـ `500` مع رسالة خطأ تصف المشكلة بدلاً من الدخول في حلقة لا نهائية.
+
+## Nitro / الـ SSR للإنتاج (الحقن التلقائي، الإصدار v9+)
+
+عند استخدام `intlayerProxy` كإضافة لـ Vite، فإنه يحمل خاصية `.nitro`. يقرأ مكون بناء `nitro/vite` هذه الخاصية ويدفعها إلى `nitroConfig.modules` ، لذلك يتم تسجيل `intlayerNitroHandler` كبرنامج وسيط لخادم Nitro تلقائيًا — لا يلزم تكوين يدوي لـ SSR الإنتاج.
+
+يستخدم معالج Nitro نموذج أحداث Web Fetch API الخاص بـ h3 v2 (وليس `fromNodeMiddleware`) لذا فهو متوافق مع جميع ملفات تعريف ومسبقات Nitro: Node، Bun، Deno، بيئات عمل الحافة (edge).
+
+## الأسماء المستعارة المهملة
+
+| التصدير المهمل             | البديل          |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/ar/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-25
 title: Intlayer v9 الجديد - ما الجديد؟
 description: اكتشف ما هو جديد في Intlayer v9. نقدم حزم توافق جاهزة للاستخدام لمكتبات i18n الشهيرة ودعمًا للمجموعات (Collections) والمتغيرات (Variants) والسجلات الديناميكية (Dynamic Records).
 keywords:
@@ -252,6 +252,50 @@ export default config;
 
 ---
 
+## React Native: استيرادات من حزمة واحدة
+
+في تطبيق React Native أو Expo، لم تعد بحاجة إلى التعامل مع كل من `react-intlayer` و`react-native-intlayer` معًا. تقوم حزمة `react-native-intlayer` الآن **بإعادة تصدير واجهة برمجة التطبيقات الكاملة لـ `react-intlayer`** (الخطافات، والأدوات المساعدة، والمسارات الفرعية `/format` و`/html` و`/markdown`)، كما يطبق `IntlayerProvider` الخاص بها حزم polyfill الخاصة بـ React Native تلقائيًا.
+
+استورد كل شيء من حزمة `react-native-intlayer` الواحدة:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> الاستيراد من `react-intlayer` لا يزال يعمل، لكن `react-native-intlayer` أصبح الآن نقطة الدخول الواحدة الموصى بها لـ React Native — يشحن موفره حزم polyfill التي لا يتضمنها موفر `react-intlayer` الموجه للويب.
+
+---
+
+## React Native: استيراد من حزمة واحدة
+
+في تطبيق React Native أو Expo، لم تعد بحاجة إلى التوفيق بين `react-intlayer` و `react-native-intlayer`. تقوم حزمة `react-native-intlayer` الآن **بإعادة تصدير واجهة برمجة تطبيقات `react-intlayer` بالكامل** (الخطافات "hooks"، والأدوات، والمسارات الفرعية `/format` و `/html` و `/markdown`)، ويقوم `IntlayerProvider` الخاص بها بتطبيق polyfills الخاصة بـ React Native تلقائيًا.
+
+قم باستيراد كل شيء من حزمة `react-native-intlayer` الفردية:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> الاستيراد من `react-intlayer` يظل يعمل، ولكن `react-native-intlayer` هي الآن نقطة الدخول الفردية الموصى بها لـ React Native — حيث يوفر المزود الخاص بها polyfills التي لا يوفرها المزود الموجه للويب `react-intlayer`.
+
+---
+
 ## ملاحظات الترحيل من الإصدار 8
 
 إذا كنت تقوم بالترقية من الإصدار 8، لاحظ أن الإصدار 9 لا يتضمن تغييرات جذرية (breaking changes). ولكن إليك التغييرات الرئيسية: