@intlayer/docs 9.3.3 → 9.4.0

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

@@ -0,0 +1,139 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: توثيق مكوّن intlayer لـ Elysia | elysia-intlayer
+description: تعرّف على كيفية استخدام المكوّن intlayer من حزمة elysia-intlayer
+keywords:
+  - intlayer
+  - elysia
+  - plugin
+  - Intlayer
+  - التدويل
+  - التوثيق
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - intlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "تهيئة التوثيق"
+author: aymericzip
+---
+
+# توثيق مكوّن intlayer لـ Elysia
+
+يقوم المكوّن `intlayer` لـ Elysia باكتشاف الـ locale الخاص بالمستخدم ويحقن كائن `intlayer` في سياق المسار (route context). كما يتيح استخدام دوال الترجمة العامة ضمن سياق الطلب.
+
+## الاستخدام
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
+  intlayer!.t({
+    ar: "مرحبًا",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+> تسجّل الإضافة سياقها عبر `derive` **عام**، والذي يعطيه Elysia النوع `Partial<{ intlayer: IntlayerContext }>`. تكون القيمة موجودة دائماً وقت التشغيل للمسارات المسجَّلة بعد `.use(intlayer())`، لذا استخدم تأكيد عدم الفراغ (`intlayer!.t`) — أو التسلسل الاختياري — لإرضاء TypeScript في الوضع `strict`.
+
+نفس الدوال المساعدة متاحة كصادرات مستقلة، بحيث يمكنك استدعاؤها دون تفكيك سياق المسار:
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer, t } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", () =>
+  t({
+    ar: "مرحبًا",
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+## الوصف
+
+يقوم المكوّن الإضافي بالمهام التالية:
+
+1. **كشف الـ locale**: يقرأ الـ locale الذي حدده العميل صراحةً من التخزين (كوكي، هيدر)، ثم يعود إلى الـ locale المتفاوض عليه من هيدر `Accept-Language`.
+2. **الحقن في السياق**: تضيف خاصية `intlayer` إلى سياق المسار في Elysia (انظر جدول سياق المسار أدناه).
+3. **إدارة السياق**: يستخدم `AsyncLocalStorage` لإدارة سياق غير متزامن، مما يسمح لدوال Intlayer العامة (`t`، `getIntlayer`، `getDictionary`) بالوصول إلى الـ locale الخاص بكل طلب دون تمرير كائن السياق.
+4. **تجهيز القواميس**: تستدعي `prepareIntlayer` عند إنشاء الإضافة، بحيث تُبنى القواميس عند إقلاع التطبيق.
+
+### سياق المسار
+
+| الخاصية           | النوع                  | الوصف                                                                             |
+| ----------------- | ---------------------- | --------------------------------------------------------------------------------- |
+| `locale`          | `Locale`               | الـ locale المستخدم لهذا الطلب، مع أولوية `locale_storage` على `locale_detected`. |
+| `locale_storage`  | `Locale` (اختياري)     | الـ locale الذي طلبه العميل صراحةً عبر كوكي أو هيدر.                              |
+| `locale_detected` | `Locale`               | الـ locale المتفاوض عليه من رؤوس الطلب.                                           |
+| `defaultLocale`   | `Locale`               | الـ locale المُعد كخيار احتياطي في `intlayer.config.ts`.                          |
+| `t`               | `TranslateFunction`    | دالة ترجمة.                                                                       |
+| `getIntlayer`     | `typeof getIntlayer`   | دالة لاسترجاع القواميس عبر المفتاح.                                               |
+| `getDictionary`   | `typeof getDictionary` | دالة لمعالجة كائنات القواميس.                                                     |
+
+> على عكس مكوّنات Intlayer المبنية على Node، يعتمد `elysia-intlayer` على `AsyncLocalStorage` بدلًا من `cls-hooked`، لأن `cls-hooked` يعتمد على `async_hooks.createHook` الذي لا يطبّقه Bun.
+
+يتم تحرير سياق الطلب بمجرد تعيين الاستجابة، بحيث لا تُحلّ الدوال المساعدة المستقلة أبدًا مقابل طلب انتهى بالفعل. وعند استدعائها خارج طلب يعالجه المكوّن، تعود إلى الـ locale الافتراضي المُعد.
+
+## ترتيب تحديد اللغة
+
+بشكل افتراضي، تحلّ الإضافة اللغة بالترتيب التالي:
+
+1. كوكي `INTLAYER_LOCALE`.
+2. ترويسة `x-intlayer-locale`.
+3. التفاوض عبر ترويسة `Accept-Language`.
+4. قيمة `defaultLocale` المُعدّة.
+
+```bash
+# تم التفاوض عليها من `Accept-Language`
+curl -H "Accept-Language: fr" http://localhost:3000/
+# Bonjour
+
+# للكوكي أولوية على `Accept-Language`
+curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
+# Hola
+
+# للترويسة أولوية على `Accept-Language`
+curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
+# Hola
+```
+
+## الإعداد
+
+يقرأ المكوّن ملف `intlayer.config.ts` الخاص بك. يمكنك تخصيص الكوكي والهيدر المستخدمين لكشف الـ locale:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> لمزيد من المعلومات حول الإعداد، تفضّل بزيارة [توثيق الإعداد](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md).
+
+## وثائق ذات صلة
+
+- [وثائق حزمة elysia-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/elysia-intlayer/exports.md)
+- [Elysia i18n - دليل شامل لترجمة تطبيقك](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_with_elysia.md)

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

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: وثائق دالة getDictionary | intlayer
+description: اطلع على كيفية استخدام دالة getDictionary لحزمة intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# التوثيق: دالة `getDictionary` في `intlayer`
+
+## الوصف
+
+تقوم دالة `getDictionary` بتفسير كائن القاموس **الذي تمرره بنفسك** وتُرجع محتواه المحلّل لمنطقة معينة. تمشي عبر المحتوى في تمريرة واحدة وتطبق كل مكون إضافي للمفسّر حسب الحاجة، محلّلة ترجمات `t()`، والتعديلات، والشروط، والإدراجات، والتداخل، والـ markdown، و HTML وعُقد الملفات.
+
+على عكس [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayer.md)، التي تبحث عن قاموس حسب المفتاح في السجل المُنتج، تأخذ `getDictionary` القاموس نفسه. هذا يجعلها الأداة المناسبة للمحتوى المُنشأ في وقت التشغيل، أو الذي تم جلبه من API أو CMS، أو المُعلن عنه بشكل مباشر في اختبار.
+
+**المميزات الرئيسية:**
+
+- تعمل مع أي كائن يتبع بنية القاموس (`{ key, content }`)
+- تقبل أيضًا مجموعة قاموس مؤهلة (المجموعات، المتغيرات) بالتزامن مع محدِّد
+- مكتوبة بالكامل: الكائن المُرجع يعكس `content` الذي مررته
+- تقبل مكونات إضافية مفسّرة مخصصة
+
+---
+
+## توقيع الدالة
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // مطلوب
+  localeOrSelector?: LocalesValues | DictionarySelector, // اختياري
+  plugins?: Plugins[]                                // اختياري
+): DeepTransformContent<...>
+```
+
+---
+
+## المعاملات
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **الوصف**: القاموس (أو مجموعة القاموس المؤهلة) الذي سيتم تفسيره.
+  - **النوع**: `Dictionary | QualifiedDictionaryGroup`
+  - **مطلوب**: نعم
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **الوصف**: اللغة لتفسير المحتوى بها، أو كائن محدد (`{ item }`, `{ variant }`, اختياري مع `locale`). انظر [القواميس الديناميكية](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md).
+  - **النوع**: `LocalesValues | DictionarySelector`
+  - **مطلوب**: لا (اختياري) — يُفترض القيمة الافتراضية `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **الوصف**: مصفوفة من محولات العقد التي تحدد كيفية تفسير العقد المعروفة. إذا تم حذفها، يتم استخدام مجموعة مفسر البرامج الإضافية الافتراضية.
+  - **النوع**: `Plugins[]`
+  - **مطلوب**: لا (اختياري)
+
+### العودة
+
+- **Type**: المحتوى المترجم للقاموس.
+- **Description**: `content` التي مررتها، مع حل كل عقدة Intlayer للغة المطلوبة. بالنسبة لمجموعة collection بدون محدد `item`، يتم إرجاع مصفوفة مرتبة من الإدخالات المترجمة؛ يتم إرجاع `null` عندما يستهدف المحدد شيئًا لا يوجد.
+
+---
+
+## مثال على الاستخدام
+
+### الاستخدام الأساسي
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        ar: "مرحبا",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "ar"
+);
+
+console.log(content.greeting); // "مرحبا"
+```
+
+### تفسير المحتوى المجلوب في وقت التشغيل
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### مع محدد
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// يتم حل مجموعة قاموس مؤهلة إلى إدخال واحد…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …أو إلى مصفوفة مرتبة عندما لا يتم إعطاء `item`
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## الدوال ذات الصلة
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayer.md): نفس التفسير، لكن يتم البحث عن القاموس حسب المفتاح في السجل المُنشأ.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getDictionaryAsync.md): نظير خرائط المحمّل لكل لغة.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/react-intlayer/useDictionary.md): معادل React hook، يقرأ اللغة من الموفر.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

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

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: توثيق دالة getDictionaryAsync | intlayer
+description: اطلع على كيفية استخدام دالة getDictionaryAsync لحزمة intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# التوثيق: دالة `getDictionaryAsync` في `intlayer`
+
+## الوصف
+
+تحمل دالة `getDictionaryAsync` جزء **منطقة لغوية واحدة** من قاموس وتعيد محتواه المفسّر.
+
+إنها نظير [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getDictionary.md) لخرائط محملات لكل منطقة لغوية المُصدرة في `.intlayer/dynamic_dictionaries/`: بدلاً من استقبال قاموس يحتوي على كل منطقة لغوية، فإنها تستقبل خريطة المحمل وتنتظر فقط الجزء الذي تحتاجه المنطقة اللغوية المطلوبة.
+
+> في كود التطبيق، عادة تستدعي [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayerAsync.md)، وليس هذه الدالة. تُعيد [مكونات البناء](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/bundle_optimization.md) كتابة كل استدعاء `getIntlayerAsync('key', locale)` إلى `getDictionaryAsync(loaderMap, 'key', locale)`. يتم تصدير `getDictionaryAsync` للمحملات المخصصة وللأدوات التي تبني خرائط محملاتها الخاصة.
+
+**الميزات الرئيسية:**
+
+- تحمل فقط جزء المنطقة اللغوية المطلوب
+- تدعم خرائط المحملات البسيطة (`locale → loader`) والمؤهلة (`locale → qualifierId → loader`)
+- تلغي التكرار للأحمال المتزامنة للجزء ذاته، وتخزن مؤقتاً المحتوى المحل
+- الأحمال الفاشلة يتم حذفها من الذاكرة المؤقتة حتى تحاول استدعاء لاحقة تحميل الجزء مجدداً
+
+---
+
+## توقيع الدالة
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // مطلوب
+  key: string,                                           // مطلوب
+  localeOrSelector?: LocalesValues | DictionarySelector, // اختياري
+  plugins?: Plugins[]                                    // اختياري
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## المعاملات
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **الوصف**: خريطة محمل لكل لغة. تربط الخرائط البسيطة لغة مع محمل؛ تربط الخرائط المؤهلة (المستخدمة في المجموعات والمتغيرات) لغة مع معرّف مؤهل، ثم مع محمل. بالنسبة للخريطة المؤهلة، يتم تحميل فقط الجزء (الأجزاء) التي يستهدفها المحدد.
+  - **النوع**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **مطلوب**: نعم
+
+- `key: string`
+  - **الوصف**: مفتاح القاموس، المستخدم في تقسيم ذاكرة التخزين المؤقت للأجزاء.
+  - **النوع**: `string`
+  - **مطلوب**: نعم
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **الوصف**: اللغة لتفسير المحتوى بها، أو كائن محدد (`{ item }`، `{ variant }`، مع `locale` اختياري). راجع [القواميس الديناميكية](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md).
+  - **النوع**: `LocalesValues | DictionarySelector`
+  - **مطلوب**: لا (اختياري) — القيمة الافتراضية هي `defaultLocale` المُعينة.
+
+- `plugins: Plugins[]`
+  - **الوصف**: محولات عقدة. القيمة الافتراضية هي مجموعة المترجم الأساسي.
+  - **النوع**: `Plugins[]`
+  - **مطلوب**: لا (اختياري)
+
+### العودة
+
+- **النوع**: `Promise<Content>` — وعد يحل إلى المحتوى المفسَّر للـ chunk المُحمَّل.
+- **الوصف**: يحل إلى `null` عندما لا ينبعث الـ map أي chunk للـ locale المطلوب أو لأي من fallbacks الخاصة به، مما يعكس كيفية حل الإحداثيات المؤهلة المفقودة.
+
+---
+
+## مثال الاستخدام
+
+### مع خريطة محمل تم إنشاؤها
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### مع خريطة محمل مخصصة
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### مع محدد على خريطة مؤهلة
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## ملاحظات السلوك
+
+### التخزين المؤقت وإزالة التكرار
+
+يخزن التخزين المؤقت **الوعد** (promise) لكل ثلاثي `key + locale + selector`، بحيث تنتظر الاستدعاءات المتزامنة للمقطع نفسه تحميلًا واحدًا. يتم إزالة التحميل المرفوض من التخزين المؤقت، لذا يتم إعادة محاولة المقطع الفاشل في الاستدعاء التالي بدلاً من إعادة تشغيل الفشل نفسه إلى الأبد.
+
+### الرجوع إلى اللغة الافتراضية
+
+يتم المرور عبر خريطة محمل عادية بنفس سلسلة الرجوع كما هو الحال في الوضع المتزامن: اللغة المطلوبة أولاً، ثم بدائلها، ثم `null` إذا لم ينشئ أي منها chunk.
+
+---
+
+## الدوال ذات الصلة
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayerAsync.md): الدالة التي تستدعيها التطبيقات؛ تعيد كتابتها بواسطة مكونات البناء إلى `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getDictionary.md): نظير متزامن يأخذ قاموس كامل.
+- [القواميس الديناميكية](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md): المجموعات والمتغيرات، وخرائط المحملات التي تولدها.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

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

@@ -29,6 +29,8 @@ author: aymericzip
 
 ## الوصف
 
+تقوم دالة `getEnumeration` (وتُعرف أيضًا بـ `enu`) باسترجاع محتوى يتوافق مع كمية معينة بناءً على شروط محددة مسبقًا في كائن تعداد. يتم تعريف الشروط كمفاتيح، ويتم تحديد أولويتها بناءً على ترتيبها في الكائن.
+
 تسترجع دالة `getEnumeration` المحتوى المقابل لكمية محددة بناءً على شروط معرفة مسبقًا في كائن التعداد. تُعرف الشروط كمفاتيح، ويتم تحديد أولويتها حسب ترتيبها في الكائن.
 
 ## المعاملات

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

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: توثيق دالة getIntlayer | intlayer
+description: انظر كيفية استخدام دالة getIntlayer لحزمة intlayer
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: دالة `getIntlayer` في `intlayer`
+
+## الوصف
+
+تقوم دالة `getIntlayer` باختيار قاموس واحد من خلال مفتاحه وتعيد محتواه المُفسَّر للغة محددة. وهي النظير المستقل عن الإطار (framework-agnostic) للربط `useIntlayer`: نفس المحتوى، نفس المحددات، لكنها قابلة للاستخدام في أي مكان لا يتوفر فيه سياق React — نصوص Node، دوال الخادم، محملات المسارات، منشئو البيانات الوصفية، معالجات Express/Fastify، الاختبارات.
+
+تقرأ القواميس التي تم إنشاؤها بواسطة Intlayer في `.intlayer/`، لذا فإن وسيط `key` له نوع ويتم إكمال سيارته تلقائياً من إعلانات المحتوى الخاصة بك، والكائن المُعاد له نوع كامل حتى كل ورقة.
+
+**الميزات الرئيسية:**
+
+- مفاتيح قاموس مكتوبة ومحتوى مُعاد مكتوب
+- تفسير كل عقدة محتوى (`t()`، `enu()`، `cond()`، `insert()`، `nest()`، `md()`، `html()`، `file()`، `gender()`)
+- قبول لغة أو كائن محدد (مجموعات، متغيرات)
+- يتم حفظ النتائج في الذاكرة لكل `key + locale + selector`
+- الرجوع إلى وكيل آمن في وضع التطوير عندما يكون القاموس مفقوداً، بدلاً من توقف البرنامج
+
+---
+
+## توقيع الدالة
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // مطلوب
+  localeOrSelector?: LocalesValues | DictionarySelector, // اختياري
+  plugins?: Plugins[]                         // اختياري
+): DeepTransformContent<...>
+```
+
+---
+
+## المعاملات
+
+- `key: DictionaryKeys`
+  - **الوصف**: مفتاح القاموس المراد قراءته، كما هو معلّن في ملفات المحتوى الخاصة بك.
+  - **النوع**: `DictionaryKeys` — اتحاد كل مفاتيح القاموس المعلنة.
+  - **مطلوب**: نعم
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **الوصف**: اللغة المراد تفسير المحتوى بها، أو كائن محدد لـ [القواميس الديناميكية](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/index.md).
+    - `'fr'` — لغة
+    - `{ item: 2 }` — عنصر [مجموعة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/collections.md) (حذف `item` للحصول على كل عنصر كمصفوفة)
+    - `{ variant: 'black-friday' }` — [متغير](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/dynamic_dictionaries/variants.md) مسمى (حذف للحصول على المتغير `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — متغير منظم
+    - أي محدد يمكنه أن يحمل لغة: `{ item: 2, locale: 'fr' }`
+  - **النوع**: `LocalesValues | DictionarySelector`
+  - **مطلوب**: لا (اختياري) — القيمة الافتراضية هي `defaultLocale` المكونة.
+
+- `plugins: Plugins[]`
+  - **الوصف**: محولات عقدة مخصصة تحل محل مكونات المُفسّر الأساسية. للاستخدام المتقدم فقط؛ حذفها للحفاظ على السلوك الافتراضي.
+  - **النوع**: `Plugins[]`
+  - **مطلوب**: لا (اختياري)
+
+### العودة
+
+- **النوع**: محتوى القاموس المُفسَّر، مُكتَّب من تصريحك.
+- **الوصف**: كائن عادي يعكس حقل `content` من قاموسك، حيث تم حل كل عقدة Intlayer إلى قيمتها النهائية للغة المطلوبة.
+
+---
+
+## مثال على الاستخدام
+
+### الاستخدام الأساسي
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      ar: "مرحبا",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### بدون locale
+
+حذف locale يفسر المحتوى باستخدام `defaultLocale` المعلنة في [الإعدادات](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // يتم تفسيره باستخدام locale الافتراضية
+```
+
+### داخل معالج الخادم
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### مع محدد (المجموعات والمتغيرات)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// عنصر مجموعة واحد
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// كل عنصر من المجموعة، كمصفوفة مرتبة
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// متغير مسمى
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## ملاحظات السلوك
+
+### التخزين المؤقت
+
+تُحفظ النتائج في ذاكرة تخزين مؤقت على مستوى الوحدة مفهرسة بـ `key + locale + selector`. استدعاء `getIntlayer("app", "fr")` بشكل متكرر يفسر القاموس مرة واحدة فقط ويعيد نفس الكائن بعد ذلك.
+
+### القواميیس المفقودة
+
+أثناء التطوير، طلب مفتاح لا توجد له قاموس مُنشأ يسجل تحذيراً مرة واحدة ويعيد بروكسي آمن للعودة: قراءة `content.title` تعطي السلسلة `"app.title"` بدلاً من رفع خطأ. هذا يحافظ على الصفحة قابلة للاستخدام بينما يتم إصلاح الإعلان المفقود. قم بتشغيل بناء Intlayer (أو خادم التطوير) حتى يتم إنشاء القاموس.
+
+### حجم الحزمة
+
+يقرأ `getIntlayer` القاموس المدمج الذي يحتوي على **كل** لغة. في حزم العميل، تعيد [ملحقات البناء](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/bundle_optimization.md) كتابة الاستدعاء بحيث يتم شحن المحتوى المطلوب فقط. عندما تقرأ المحتوى خارج التصيير (البيانات الوصفية، المحملات، وظائف الخادم) وتريد تحميل لغة واحدة حسب الطلب، استخدم [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayerAsync.md) بدلاً من ذلك.
+
+---
+
+## الدوال ذات الصلة
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayerAsync.md): نظير غير متزامن يحمل مجموعة منطقة واحدة.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getDictionary.md): يفسر كائن القاموس الذي تمرره بنفسك، بدلاً من البحث عنه حسب المفتاح.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/react-intlayer/useIntlayer.md): معادل React hook، يقرأ المنطقة من موفر الخدمة.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```