@intlayer/docs 9.1.3 → 9.2.0

package/docs/ar/intlayer_with_vite+vue.md

@@ -30,9 +30,7 @@ history:
 author: aymericzip
 ---
 
-# ترجم Vite and Vue باستخدام Intlayer | التدويل (i18n)
-
-راجع [قالب التطبيق](https://github.com/aymericzip/intlayer-vite-vue-template) على GitHub.
+# ترجمة موقع Vite و Vue الخاص بك باستخدام Intlayer | Internationalization (i18n)
 
 ## جدول المحتويات
 

package/docs/ar/packages/intlayer/getLocalizedUrl.md

@@ -63,30 +63,32 @@ getLocalizedUrl(
   - **Type**: `Locales`
   - **Required**: Yes
 
-## المعاملات
-
-- `url: string`
-  - **الوصف**: سلسلة عنوان URL الأصلية التي سيتم إضافة بادئة اللغة إليها.
-  - **النوع**: `string`
-
-- `currentLocale: Locales`
-  - **الوصف**: اللغة الحالية التي يتم تعريب العنوان لها.
-  - **النوع**: `Locales`
-
-- `locales: Locales[]`
-  - **الوصف**: مصفوفة اختيارية من اللغات المدعومة. بشكل افتراضي، يتم توفير اللغات المكونة في المشروع.
-  - **النوع**: `Locales[]`
-  - **الافتراضي**: [`تكوين المشروع`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
-
-- `defaultLocale: Locales`
-  - **الوصف**: اللغة الافتراضية للتطبيق. بشكل افتراضي، يتم توفير اللغة الافتراضية المكونة في المشروع.
-  - **النوع**: `Locales`
-  - **الافتراضي**: [`تكوين المشروع`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
-
-- `prefixDefault: boolean`
-  - **الوصف**: ما إذا كان يجب إضافة بادئة للعنوان الافتراضي. بشكل افتراضي، يتم توفير القيمة المكونة في المشروع.
-  - **النوع**: `boolean`
-  - **الافتراضي**: [`تكوين المشروع`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
+### المعاملات الاختيارية
+
+- `options?: object`
+  - **الوصف**: كائن التكوين لسلوك تحديد موقع عناوين URL.
+  - **النوع**: `object`
+  - **مطلوب**: لا (اختياري)
+
+  - `options.locales?: Locales[]`
+    - **الوصف**: مصفوفة اللغات المدعومة. إذا لم يتم توفيرها، فسيتم استخدام اللغات المكونة من تكوين مشروعك.
+    - **النوع**: `Locales[]`
+    - **القيمة الافتراضية**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **الوصف**: اللغة الافتراضية للتطبيق. إذا لم يتم توفيرها، فسيتم استخدام اللغة الافتراضية المكونة من تكوين مشروعك.
+    - **النوع**: `Locales`
+    - **القيمة الافتراضية**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **الوصف**: وضع التوجيه للعنوان لمعالجة اللغة. إذا لم يتم توفيره، فسيتم استخدام الوضع المكون من تكوين مشروعك.
+    - **النوع**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **القيمة الافتراضية**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md#middleware)
+    - **الأوضاع**:
+      - `prefix-no-default`: بدون بادئة للغة الافتراضية، بادئة لجميع اللغات الأخرى
+      - `prefix-all`: بادئة لجميع اللغات بما في ذلك اللغة الافتراضية
+      - `no-prefix`: بدون بادئة لغة في العنوان
+      - `search-params`: استخدام معاملات الاستعلام للغة (مثل `?locale=fr`)
 
 ### الإرجاع
 

package/docs/ar/packages/intlayer/getMultilingualUrls.md

@@ -49,26 +49,12 @@ author: aymericzip
 
 ## المعاملات
 
-## المعاملات
+### المعاملات المطلوبة
 
 - `url: string`
-  - **الوصف**: سلسلة عنوان URL الأصلية التي سيتم إضافة بادئات اللغات إليها.
-  - **النوع**: `string`
-
-- `locales: Locales[]`
-  - **الوصف**: مصفوفة اختيارية من اللغات المدعومة. القيمة الافتراضية هي اللغات المعرفة في المشروع.
-  - **النوع**: `Locales[]`
-  - **الافتراضي**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **الوصف**: اللغة الافتراضية للتطبيق. القيمة الافتراضية هي اللغة الافتراضية المعرفة في المشروع.
-  - **النوع**: `Locales`
-  - **الافتراضي**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **الوصف**: ما إذا كان يجب إضافة بادئة للغة الافتراضية. القيمة الافتراضية هي القيمة المعرفة في المشروع.
-  - **النوع**: `boolean`
-  - **الافتراضي**: `prefixDefaultDefault`
+  - **Description**: سلسلة URL الأصلية التي سيتم إضافة البادئة لها باستخدام اللغات.
+  - **Type**: `string`
+  - **Required**: نعم
 
 ### المعاملات الاختيارية
 

package/docs/ar/packages/react-intlayer/useDictionary.md

@@ -24,6 +24,10 @@ history:
 author: aymericzip
 ---
 
+# توثيق Hook useDictionary
+
+يسمح hook `useDictionary` بمعالجة كائن يشبه القاموس (يحتوي على مفاتيح ومحتوى) والتعامل مع الترجمات والتعددات وما إلى ذلك بداخله. بخلاف `useIntlayer`، الذي تم تصميمه للعمل مع إعلانات القاموس المُنشأة، فإن `useDictionary` أكثر مرونة ويمكن استخدامه مع أي كائن يتبع هيكل القاموس.
+
 ## مثال على الاستخدام في React
 
 فيما يلي مثال على كيفية استخدام الخطاف `useDictionary` في مكون React:
@@ -45,27 +49,6 @@ const ComponentExample: FC = () => {
 };
 ```
 
-## التكامل مع الخادم
-
-إذا كنت تستخدم الخطاف `useDictionary` خارج `IntlayerProvider`، يجب توفير اللغة صراحة كمعامل عند عرض المكون:
-
-```tsx fileName="./ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useDictionary } from "react-intlayer/server";
-import clientComponentExampleContent from "./component.content";
-
-const ServerComponentExample: FC<{ locale: string }> = ({ locale }) => {
-  const { content } = useDictionary(clientComponentExampleContent, locale);
-
-  return (
-    <div>
-      <h1>{content.title}</h1>
-      <p>{content.content}</p>
-    </div>
-  );
-};
-```
-
 ## نصائح إضافية
 
 - **سلامة النوع**: استخدم دائمًا `Dictionary` لتعريف القواميس الخاصة بك لضمان سلامة النوع.

package/docs/ar/packages/react-intlayer/useIntlayer.md

@@ -21,9 +21,9 @@ slugs:
 author: aymericzip
 ---
 
-## القاموس
+# توثيق خطاف useIntlayer
 
-يجب إعلان جميع مفاتيح القاموس داخل ملفات إعلان المحتوى لتعزيز أمان النوع وتجنب الأخطاء. يمكنك العثور على [تعليمات الإعداد هنا](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dictionary/content_file.md).
+يسمح خطاف `useIntlayer` بالحصول على محتوى محلي من قاموس باستخدام مفتاحه. وهو يعتمد على `useDictionary` لكنه يحقن تلقائياً نسخة محسّنة من القاموس من التصريحات المُنشأة.
 
 ## مثال على الاستخدام في React
 

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

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | مكوّن إضافي أثناء التطوير للتعامل مع اكتشاف اللغة والتوجيه.              | -                                                                                                                      |
 | `intlayerMiddleware` | (**مهمل**) مرادف لـ `intlayerProxy`.                                     | -                                                                                                                      |
 | `intlayerPrune`      | ملحق لإجراء tree-shake وتقليم القواميس غير المستخدمة أثناء عملية البناء. | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayerPrune.md) |
+
+### الأدوات
+
+| التصدير                      | الوصف                                                                                        | المستند ذو الصلة                                                                                                       |
+| ---------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | إرجاع middleware لـ Node.js `(req, res, next)` غير متعلق بأي framework مع منطق توجيه locale. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayerProxy.md) |
+
+### الأنواع
+
+| التصدير                      | الوصف                                                                                                          |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | الخيارات المقبولة بواسطة `intlayer()`. تمتد `GetConfigurationOptions` مع `compatCallers` و `proxy`.            |
+| `IntlayerProxyPluginOptions` | الخيارات المقبولة بواسطة `intlayerProxy()` و `createIntlayerProxyHandler()`. تتضمن `ignore` و `configOptions`. |
+| `IntlayerCompilerOptions`    | الخيارات المقبولة بواسطة `intlayerCompiler()`. تتضمن `configOptions` و `compilerConfig`.                       |
+| `CompatCallerConfig`         | إعادة تصدير من `@intlayer/babel`. يصف نمط compat-adapter caller لتحليل استخدام الحقول.                         |

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

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## الوصف
+## الخيارات
 
-يقوم الملحق بالمهام التالية:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` يوسع `GetConfigurationOptions` (انظر `@intlayer/config`) مع الحقول الإضافية التالية:
+
+| الخيار          | النوع                           | القيمة الافتراضية | الوصف                                                                                                                           |
+| --------------- | ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`              | أنماط استدعاء إضافية لحزم compat-adapter (مثل `@intlayer/react-i18next`). يتم تمريرها إلى محلل استخدام الحقول في وقت البناء.    |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined`       | خيارات يتم تمريرها إلى وكيل توجيه المنطقة المرفقة. استخدم `ignore` لاستبعاد المسارات المحددة (مثل مسارات API) من توجيه المنطقة. |
+
+يتم تمرير جميع الخيارات الأخرى (`override`, `configFile`, …) مباشرة إلى `getConfiguration()`.
+
+### أمثلة
+
+#### تجاهل مسارات API من توجيه اللغة
+
+```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"),
+      },
+    }),
+  ],
+});
+```
+
+#### مع مسار ملف config مخصص
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### مع استدعاءات compat-adapter
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## ما يفعله البرنامج الإضافي
+
+### 1. تحضير القاموس
+
+قبل بدء البناء (وكل ساعة واحدة في بيئة التطوير)، يستدعي `intlayer` الدالة `prepareIntlayer` لترجمة جميع ملفات `.content.ts` إلى قواميس JSON محسنة مخزنة في `.intlayer/`.
+
+### 2. أسماء مستعارة للوحدات
+
+يضيف البرنامج الإضافي أسماء مستعارة لحل Vite بحيث يتم حل `import { myDict } from 'intlayer/dictionaries/my-dict'` إلى ملف JSON مترجم على القرص. تستخدم عمليات بناء SSR `ssr.noExternal` للتأكد من أن جميع حزم `@intlayer/*` موجودة مع تطبيق الأسماء المستعارة.
+
+### 3. مراقب خادم التطوير
+
+في وضع التطوير، يتم بدء مراقب `chokidar`. عند تغيير ملف `.content.ts`، يتم إعادة تجميع القواميس وينتشر تحديث Vite's HMR إلى المتصفح.
+
+### 4. وسيط توجيه المنطقة المدمج (v9+)
+
+منذ إصدار Intlayer v9، يتم تسجيل middleware `intlayerProxy` تلقائياً داخل `intlayer()`. يتعامل مع:
+
+- كشف المنطقة من بادئة URL والكوكيز ورأس `Accept-Language`.
+- إعادة توجيه 301 عندما لا تتطابق المنطقة المكتشفة مع عنوان URL الحالي.
+- إعادة كتابة URL داخلية بحيث يرى الإطار معامل المسار `[locale]` الصحيح.
+
+يتم التحكم في الوسيط بواسطة `routing.enableProxy` (الافتراضي `true`) في إعدادات Intlayer الخاصة بك. لتعطيله بالكامل:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+لتخصيص سلوك الوسيط دون استدعاء `intlayerProxy()` منفصل، مرر خيارات `proxy` إلى المكون الإضافي الرئيسي:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+راجع [وثائق intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayerProxy.md) للحصول على مرجع سلوك التوجيه الكامل.
+
+### 5. مجمِّع مرفق (v9+)
+
+عندما يكون `compiler.enabled` هو `true` **و** يتم تعيين `compiler.output` في إعدادات Intlayer الخاصة بك، يسجل `intlayer()` `intlayerCompiler` تلقائياً. يستخرج المجمِّع إعلانات المحتوى المضمنة المكتوبة مباشرة داخل ملفات المكونات ويكتبها إلى القواميس في وقت التحويل. انظر [وثائق intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. تحسينات البناء
+
+أثناء بناء الإنتاج، تضيف الإضافة:
+
+- **intlayerOptimize** – تحويل Babel الذي يعيد كتابة `useIntlayer('key')` → `useDictionary(hash)` وحقن واردات JSON المباشرة.
+- **intlayerPrune** – يزيل حقول المحتوى غير المستخدمة من قاموس JSON.
+- **intlayerMinify** – يضغط قاموس JSON ويمكن أن يعيد تسمية أسماء الحقول اختياريًا.
+
+هذه غير نشطة في وضع التطوير.
+
+## الأسماء المستعارة المهجورة
 
-1. **تحضير القواميس**: يقوم بتجميع القواميس إلى ملفات مُحسّنة في بداية عملية البناء أو تشغيل وضع التطوير.
-2. **وضع المراقبة**: في وضع التطوير، يراقب التغييرات في ملفات القواميس ويُعيد تجميعها تلقائيًا.
-3. **الاختصارات (Aliases)**: يوفر اختصارات للوصول إلى القواميس في تطبيقك.
-4. **Tree-shaking**: يدعم إزالة الترجمات غير المستخدمة عبر الإضافة `intlayerPrune`.
+| الصادرات المهجورة | البديل     |
+| ----------------- | ---------- |
+| `intlayerPlugin`  | `intlayer` |
+| `intLayerPlugin`  | `intlayer` |

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

@@ -30,16 +30,83 @@ author: aymericzip
 
 ## الاستخدام
 
+### كجزء من `intlayer()` (موصى به)
+
+قم بتفعيل التنقية من خلال إعدادات Intlayer والمكون الرئيسي يتعامل مع كل شيء:
+
 ```ts
-// ملف vite.config.ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // تفعيل كل من التنقية والضغط
+  },
+});
+```
+
+```ts
+// vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [intlayer()],
 });
 ```
 
+### مستقل
+
+إذا كنت تؤلف مكدس المكونات الإضافية يدويًا، فإن `intlayerPrune` و `intlayerMinify` يشتركان في كائن `PruneContext` يجب إنشاؤه مرة واحدة وتمريره إلى كليهما:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // اختياري، يقرأ من نفس السياق
+  ],
+});
+```
+
+## كيف يعمل
+
+### 1. تحليل الاستخدام (buildStart)
+
+أثناء `buildStart`، يقوم plugin `intlayerOptimize` (وهو أيضًا جزء من `intlayer()`) بفحص كل ملف مصدر مكون مدرج في `build.filesList`. لكل استدعاء `useIntlayer('key')` أو `getIntlayer('key')`، يسجل بالضبط الحقول التي تم الوصول إليها، على سبيل المثال:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// السجل: myDict → { title, description }
+```
+
+وهذا يبني `pruneContext.fieldUsageMap` قبل تشغيل أي استدعاءات `transform`.
+
+### 2. تقليص JSON (transform, enforce: 'pre')
+
+عندما تعالج Vite ملف قاموس JSON مُترجَم، يعترض `intlayerPrune` عملية التحويل قبل تحويل JSON → ESM المدمج في Vite. يقرأ خريطة استخدام الحقول من `pruneContext` ويزيل أي حقل محتوى غير مسجل في مجموعة الاستخدام.
+
+تُدعم شكلان من المحتوى:
+
+- **القواميیس الثابتة** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. يتم تقليص الحقول لكل لغة داخل `translation`.
+- **القواموس الديناميكية (لكل لغة)** — `{ fieldA: ..., fieldB: ... }` مسطحة. يتم تقليص الحقول على المستوى الأعلى.
+
+### 3. حالات خاصة
+
+إذا لم يتمكن النظام من التعرف على هيكل محتوى القاموس (على سبيل المثال، شكل متداخل غير عادي)، يتم إضافته إلى `pruneContext.dictionariesWithEdgeCases` و**تركه دون تعديل**. يتم تسجيل تحذير. يتخطى `intlayerMinify` أيضاً هذه القواميس.
+
+### 4. خريطة إعادة تسمية الحقول
+
+عند نجاح التقليص، يكتب `intlayerPrune` أيضًا `pruneContext.dictionaryKeyToFieldRenameMap` — وهي خريطة من أسماء الحقول الأصلية إلى اسم مستعار قصير. يقرأ `intlayerMinify` هذه الخريطة لإعادة تسمية الحقول في JSON الناتج، وتحديث Babel الخاص بـ `intlayerOptimize` يحدّث عمليات الوصول إلى الخصائص في ملفات المصدر وفقًا لذلك.
+
 ## الوصف
 
 يقوم المكوّن الإضافي بتحليل شفرة المصدر الخاصة بك لتحديد مفاتيح القواميس المستخدمة فعليًا. ثم يزيل أي محتوى غير مستخدم من ملفات القواميس المدرجة في الحزمة (bundle). يكون هذا مفيدًا بشكل خاص للمشاريع الكبيرة التي تحتوي على العديد من القواميس حيث يُستخدم جزء فقط منها في صفحات أو مكونات محددة.

package/docs/ar/releases/v9.md

@@ -335,28 +335,6 @@ npm install intlayer react-native-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`.
-
----
-
 ## CMS SDK: استخدم Intlayer كقاعدة بيانات محتوى headless
 
 يأتي Intlayer v9 مع SDK نظيف وذاتي المصادقة في `@intlayer/api` للتفاعل مع نظام إدارة المحتوى (CMS) برمجيًا — جلب المشاريع، وجلب القواميس، ودفعها أو تحديثها من خادمك أو سكربتاتك أو CI الخاص بك. تتم المصادقة (OAuth2 `client_credentials`) وتجديدها نيابةً عنك.
@@ -395,21 +373,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 يقوم المثبّت بتنزيل ملف `docker-compose.yml` وملف `.env`، ويولّد الأسرار المطلوبة تلقائياً، ويشغّل `docker compose up -d`. كل شيء — لوحة التحكم، وواجهة برمجة التطبيقات، وقاعدة البيانات، وتخزين الكائنات، والبريد الإلكتروني التفاعلي — يعمل محلياً داخل حاويات.
 
-### الخدمات المتضمنة
-
-| الخدمة                                           | الغرض                                                                   |
-| ------------------------------------------------ | ----------------------------------------------------------------------- |
-| **app** (TanStack Start)                         | واجهة لوحة التحكم على المنفذ `3000`                                     |
-| **backend** (Fastify/Bun)                        | واجهة برمجة تطبيقات REST على المنفذ `3100`                              |
-| **MongoDB 7** (مجموعة نسخ متماثلة أحادية العقدة) | قاعدة البيانات الرئيسية                                                 |
-| **Redis 7**                                      | قوائم انتظار المهام والتخزين المؤقت                                     |
-| **MinIO**                                        | تخزين كائنات متوافق مع S3 (الصور الرمزية، لقطات الشاشة)                 |
-| **Mailpit**                                      | خادم SMTP محلي + واجهة ويب للبريد الإلكتروني التفاعلي على المنفذ `8025` |
-
-يتم تضمين Chromium (المستخدم لتوليد لقطات الشاشة عبر Puppeteer) داخل صورة الخادم الخلفي — دون الحاجة إلى حاوية إضافية.
-
----
-
 ## ملاحظات الترحيل من الإصدار 8
 
 إذا كنت تقوم بالترقية من الإصدار 8، لاحظ أن الإصدار 9 لا يتضمن تغييرات جذرية (breaking changes). ولكن إليك التغييرات الرئيسية:

package/docs/ar/self_hosting.md

@@ -80,6 +80,18 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+## إعداد التشغيل الأول
+
+على نسخة جديدة (قاعدة بيانات فارغة)، يعيد فتح لوحة التحكم توجيهك إلى صفحة **`/init`**:
+
+1. أنشئ الحساب الأول. نظراً لأن مجموعة المستخدمين فارغة، يتم ترقية هذا الحساب تلقائياً إلى **super admin**.
+2. يتم إرسال بريد إلكتروني للتحقق (عبر Resend). التحقق من البريد الإلكتروني **إلزامي** — وهذا هو السبب في أنه يجب تعيين `RESEND_API_KEY` قبل أن تبدأ.
+3. انقر على الرابط في البريد الإلكتروني، ثم قم بتسجيل الدخول.
+
+بمجرد وجود admin، يعيد `/init` التوجيه إلى صفحة تسجيل الدخول القياسية.
+
+---
+
 ## الخدمات
 
 | الخدمة      | الصورة                               | المنفذ (المضيف)                     | الغرض                                                  |
@@ -99,7 +111,16 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ## متغيرات البيئة
 
-يولّد المثبّت ملف `.env` جاهزاً للاستخدام. يصف الجدول أدناه كل متغير.
+### مطلوب
+
+| المتغير                | مثال                         | الوصف                                                                                                                                         |
+| ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | مستخدم MongoDB Atlas                                                                                                                          |
+| `DB_MDP`               | _(كلمة المرور الخاصة بك)_    | كلمة مرور MongoDB Atlas                                                                                                                       |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | مضيف مجموعة MongoDB Atlas (المستخدم في URI `mongodb+srv://`)                                                                                  |
+| `BETTER_AUTH_SECRET`   | _(تم إنشاؤها)_               | سر بحجم 32 بايت لتوقيع الجلسة                                                                                                                 |
+| `S3_SECRET_ACCESS_KEY` | _(تم إنشاؤها)_               | السر الخاص بـ MinIO المضمن                                                                                                                    |
+| `RESEND_API_KEY`       | _(مفتاحك)_                   | البريد الإلكتروني المعاملاتي عبر Resend. مطلوب لإعداد التشغيل الأول إلا إذا قمت بتكوين mailer SMTP عام (انظر [Global mailer](#global-mailer)) |
 
 ### المطلوبة (مولّدة تلقائياً أو مطلوبة)
 
@@ -141,6 +162,26 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+### بريد عام
+
+بشكل افتراضي، يتم إرسال جميع رسائل البريد الإلكترونية للمعاملات عبر Resend باستخدام `RESEND_API_KEY`. يمكن للنشرات ذاتية الاستضافة بدلاً من ذلك توجيه **كل** بريد إلكتروني — بما في ذلك رسائل البريد الإلكترونية غير المتعلقة بالمنظمة مثل إعادة تعيين كلمات المرور والروابط السحرية — عبر بريد عام مُعد باستخدام متغيرات البيئة.
+
+عيّن `MAIL_PROVIDER` لتفعيله. عند عدم التعيين، يتم استخدام بريد Resend الافتراضي.
+
+| المتغير              | مثال                           | الوصف                                                                          |
+| -------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
+| `MAIL_PROVIDER`      | `smtp`                         | النقل العام: `smtp` أو `resend`. اترك بدون تعيين لاستخدام الإعدادات الافتراضية |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | رأس المُرسل. يقبل عنوان مجرد أو تنسيق `Name <email>`                           |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | مضيف SMTP (مطلوب عند `MAIL_PROVIDER=smtp`)                                     |
+| `MAIL_SMTP_PORT`     | `587`                          | منفذ SMTP (الافتراضي `587`)                                                    |
+| `MAIL_SMTP_SECURE`   | `false`                        | TLS ضمني. عيّن `true` للمنفذ `465`                                             |
+| `MAIL_SMTP_USER`     | _(اسم المستخدم الخاص بك)_      | اسم مستخدم SMTP (اختياري؛ تجاهل للمرحلات غير المصرح بها)                       |
+| `MAIL_SMTP_PASSWORD` | _(كلمة المرور الخاصة بك)_      | كلمة مرور SMTP                                                                 |
+
+> الأولوية: بريد المنظمة الخاص بها (المُعد من لوحة المعلومات **Organization**) له الأولوية على البريد العام، والذي له بدوره الأولوية على مفتاح Resend الافتراضي.
+
+---
+
 ## ربط مشروعك بـ Intlayer
 
 بمجرد تشغيل المكدس، وجّه مشروعك نحو الخادم الخلفي ولوحة التحكم المستضافَين ذاتياً بدلاً من `intlayer.org`.
@@ -259,47 +300,11 @@ docker run --rm \
 
 ---
 
-## استخدام وكيل عكسي (Nginx / Caddy)
-
-للنشر في الإنتاج، ضع وكيلاً عكسياً أمام حاويات التطبيق والخادم الخلفي بدلاً من كشفها مباشرة.
+## القيود
 
-### مثال Nginx
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-حدّث متغيرات البيئة التالية في `.env` لتتناسب مع نطاقاتك العامة:
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> تُخبز متغيرات `VITE_*` في صورة لوحة التحكم عند وقت البناء. إذا غيّرتها بعد بناء الصورة، ستحتاج إلى إعادة بناء صورة `app` (`docker compose build app`) أو استخدام حقن التهيئة في وقت التشغيل.
+- **MongoDB يجب أن يكون خارجياً (Atlas).** يتصل الخادم الخلفي فقط عبر `mongodb+srv://` (مبني من `DB_ID` / `DB_MDP` / `DB_CLUSTER`)، لذا لا يمكن استخدام `mongodb://host:27017` العادي — بما في ذلك `mongod` المدمج في الحاوية الخاصة — لا يمكن استخدامه. قدم مجموعة MongoDB Atlas.
+- **لا توجد نطاقات مخصصة.** جميع عناوين URL الموجهة للمتصفح `VITE_*` مدرجة مباشرة في التطبيق وقت البناء، والصورة المنشورة تأتي مع قيم `localhost`. يجب الوصول إلى لوحة التحكم على `http://localhost:3000`؛ تقديمها على نطاق عام سيتطلب إعادة بناء الصورة مع عناوين URL المستهدفة المدمجة فيها وليس مدعوماً بشكل افتراضي.
+- **البريد الإلكتروني يتطلب خادم بريد يعمل.** إعداد التشغيل الأول يفرض التحقق من البريد الإلكتروني، لذا يجب تكوين إما `RESEND_API_KEY` أو [خادم SMTP عام](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`). بعد دخول المسؤول الأول، يمكن لكل منظمة أيضاً تكوين خادم SMTP أو Resend الخاص بها من لوحة التحكم.
 
 ---
 
@@ -324,14 +329,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### البريد الإلكتروني لا يُرسل
-
-افتراضياً، يتم التقاط جميع البريد الصادر بواسطة Mailpit. افتح `http://localhost:8025` لرؤية الرسائل المرسلة. لإرسال بريد إلكتروني حقيقي، اضبط `MAIL_PROVIDER=resend` و`RESEND_API_KEY=<your-key>` في `.env`، ثم أعد تشغيل الخادم الخلفي:
-
-```sh
-docker compose restart backend
-```
-
 ### دلو MinIO مفقود
 
 إذا لم تُشغَّل خدمة `minio-init` المؤقتة (أو شُغّلت قبل أن يكون MinIO جاهزاً)، أنشئ الدلو يدوياً: