@intlayer/docs 9.4.0-canary.0 → 9.4.0

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>
+>;
+```

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

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: توثيق دالة getIntlayerAsync | intlayer
+description: انظر كيفية استخدام دالة getIntlayerAsync لحزمة intlayer
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# التوثيق: دالة `getIntlayerAsync` في `intlayer`
+
+## الوصف
+
+تقوم دالة `getIntlayerAsync` باختيار قاموس واحد حسب مفتاحه وحل محتواه للغة معينة، **محملة تلك اللغة وحدها**.
+
+إنها النظير غير المتزامن لـ [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayer.md)، مخصصة للأماكن التي يتم فيها قراءة القاموس خارج العرض — منشئات `head` / metadata للمسار، loaders، server functions.
+
+حيث يسحب `getIntlayer` القاموس المدمج الذي يحتوي على كل لغة، فإن [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) تعيد كتابة هذا الاستدعاء إلى `getDictionaryAsync(loaderMap, key, locale)`، مشيرة إلى أجزاء كل لغة في `.intlayer/dynamic_dictionaries/`. وبالتالي، يحمل bundle فقط اللغة المطلوبة فعلياً.
+
+بدون هذه البرامج المساعدة — بناء غير محسّن — يتم حل الاستدعاء من خلال سجل القاموس المتزامن بدلاً من ذلك: نفس المحتوى، بدون تقسيم اللغة.
+
+**الميزات الرئيسية:**
+
+- نفس المفاتيح المكتوبة والمحددات والمحتوى المُرجع مثل `getIntlayer`
+- يحمل فقط جزء اللغة المطلوب في الإنشاءات المحسّنة
+- الاستدعاءات المتزامنة لنفس الجزء تشارك تحميلاً واحداً
+- آمن للاستخدام في منشئات `async` metadata و loaders و server functions
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // مطلوب
+  localeOrSelector?: LocalesValues | DictionarySelector, // اختياري
+  plugins?: Plugins[]                         // اختياري
+): Promise<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[]`
+  - **مطلوب**: لا (اختياري)
+
+### المخرجات
+
+- **Type**: `Promise<Content>` — وعد يتم حله إلى المحتوى المفسر للقاموس، مكتوب من إعلانك.
+
+---
+
+## مثال الاستخدام
+
+### الاستخدام الأساسي
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` مقابل `getIntlayerAsync`
+
+|                  | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                      |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| الإرجاع          | المحتوى                                                                                                         | وعد بالمحتوى                            |
+| القاموس المحمّل  | القاموس المدمج (جميع اللغات)                                                                                    | جزء اللغة المطلوبة فقط                  |
+| الأنسب للـ       | العرض، مسارات الكود المتزامنة                                                                                   | البيانات الوصفية، المحملات، دوال الخادم |
+| هل يتطلب plugin؟ | لا                                                                                                              | لا — تقسيم كل لغة يتطلب build plugins   |
+
+كلاهما يقبل نفس المعاملات ويعيد نفس المحتوى: التبديل من أحدهما إلى الآخر يغير فقط **متى** و**كم** يتم تحميله.
+
+---
+
+## الوظائف ذات الصلة
+
+- [`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): الدالة منخفضة المستوى التي تعيد كتابتها إضافات البناء إلى هذا الاستدعاء.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getLocale.md): يكتشف لغة الطلب الوارد.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

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

@@ -59,7 +59,5 @@ getLocaleLang(Locales.FRENCH); // الناتج: "fr"
 
 - **عدم توفير الموقع:**
 
-- تُعيد الدالة سلسلة فارغة عندما يكون `locale` غير معرف (`undefined`).
-
 - **سلاسل الموقع المشوهة:**
   - إذا لم يتبع `locale` تنسيق `language-country` (مثلًا، `Locales.ENGLISH-US`)، فإن الدالة تُعيد بأمان الجزء الذي يسبق `'-'` أو السلسلة كاملة إذا لم يكن هناك `'-'`.

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

@@ -31,6 +31,8 @@ author: aymericzip
 
 تقوم دالة `getLocalizedPath` بتحويل المسار القانوني (المسار الداخلي للتطبيق) إلى نظيره المحلي بناءً على الـ locale وقواعد إعادة الكتابة (rewrite rules) المقدمة. تكون هذه الدالة مفيدة بشكل خاص عند إنشاء عناوين URL صديقة لمحركات البحث تختلف بحسب اللغة.
 
+إنه نظير نسبي لـ [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getLocalizedUrl.md) — بالنسبة للمدخل النسبي يعيد كلاهما نفس القيمة. على عكس `getLocalizedUrl`، لا يعيد أبداً عنوان URL مطلق: يتم تجاهل إعداد `domains`، لذا فإن اللغة المقدمة من نطاقها الخاص لا تزال تسفر عن مسار. يتم قبول المدخل المطلق، لكن يتم حذف أصله — يتم الاحتفاظ فقط بمساره وسلسلة الاستعلام والـ hash.
+
 **الميزات الرئيسية:**
 
 - يدعم معلمات المسارات الديناميكية باستخدام صيغة `[param]`.
@@ -60,13 +62,17 @@ getLocalizedPath(
   - **النوع**: `string`
   - **مطلوب**: نعم
 
-- `locale: Locales`
-  - **الوصف**: المحلي/اللغة المستهدفة التي يجب أن يتم تعريب المسار بناءً عليها.
-  - **النوع**: `Locales`
-  - **مطلوب**: نعم
-
 ### المعلمات الاختيارية
 
+- `locale?: Locales`
+  - **Description**: اللغة المستهدفة التي يجب تحويل المسار إليها.
+  - **Type**: `Locales`
+  - **Default**: اللغة الافتراضية لإعدادات مشروعك.
+
+- `options?: object`
+  - **Description**: تجاوزات التوجيه. كل إدخال يستخدم افتراضيات من إعدادات مشروعك.
+  - **Type**: `object`
+
 - `rewriteRules?: RoutingConfig['rewrite']`
   - **الوصف**: كائن يعرّف قواعد إعادة الكتابة المخصصة. إذا لم يتم توفيره، فسيكون الافتراضي هو الخاصية `routing.rewrite` من تكوين مشروعك.
   - **النوع**: `RoutingConfig['rewrite']`
@@ -79,6 +85,28 @@ getLocalizedPath(
 - **النوع**: `string`
 - **الوصف**: المسار المعرب للمحلي المحدد.
 
+النوع مضيق من قواعد إعادة الكتابة المعلنة في التكوين الخاص بك، لذلك يعرض المحرر المسار المحلول بدلاً من `string` مجرد:
+
+```typescript codeFormat="typescript"
+// التكوين: الوضع 'prefix-no-default'، defaultLocale 'en'،
+//                { '/about': { fr: '/a-propos' }, '/product/[id]': { fr: '/produit/[id]' } }
+const about = getLocalizedPath("/about", Locales.FRENCH);
+//    ^? '/fr/a-propos'
+const product = getLocalizedPath("/product/123", Locales.FRENCH);
+//    ^? '/fr/produit/123'
+const contact = getLocalizedPath("/contact", Locales.FRENCH);
+//    ^? '/fr/contact'  (لا توجد قاعدة إعادة كتابة مطابقة، يتم تطبيق البادئة فقط)
+const home = getLocalizedPath("/", Locales.FRENCH);
+//    ^? '/fr'
+```
+
+يتدفق التضييق نفسه إلى [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/packages/intlayer/getLocalizedUrl.md)، الذي يطبق قواعد إعادة الكتابة قبل إضافة بادئة اللغة.
+
+حالتان تبقى موسعة إلى `string`، لأنه لا يمكن حلهما في وقت الترجمة:
+
+- مسار ليس حرفيًا (مثلاً، مسار تم إنشاؤه من متغير);
+- مسار يطابق قاعدة تستخدم معامل متعدد القطاعات أو اختياري (`[...slug]`, `[[...slug]]`, `:param?`).
+
 ---
 
 ## مثال على الاستخدام
@@ -126,8 +154,6 @@ getLocalizedPath("/contact", Locales.FRENCH, manualRules);
 // Output: "/contactez-nous"
 ```
 
----
-
 ### حذف الإعدادات الإقليمية
 
 عندما لا يتم تحديد أي إعدادات إقليمية، يتم تحديد المسار للإعدادات الإقليمية الافتراضية المكونة:

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

@@ -31,6 +31,14 @@ author: aymericzip
 
 تقوم دالة `getLocalizedUrl` بإنشاء عنوان URL محلي عن طريق إضافة بادئة اللغة المحددة إلى عنوان URL المعطى. تتعامل مع عناوين URL المطلقة والنسبية على حد سواء، مما يضمن تطبيق بادئة اللغة الصحيحة بناءً على التكوين.
 
+**المميزات الرئيسية:**
+
+- معاملان فقط مطلوبان: `url` و `currentLocale`
+- كائن `options` اختياري يحتوي على `locales` و `defaultLocale` و `mode`
+- يستخدم تكوين التدويل في مشروعك كقيم افتراضية
+- يمكن استخدامه بمعاملات بسيطة للحالات البسيطة أو تخصيصه بالكامل للسيناريوهات المعقدة
+- يدعم أوضاع توجيه متعددة: `prefix-no-default` و `prefix-all` و `no-prefix` و `search-params`
+
 ---
 
 ## توقيع الدالة
@@ -135,36 +143,6 @@ getLocalizedUrl(
 // الناتج: "/about" للغة الافتراضية (الإنجليزية)
 ```
 
-```javascript codeFormat="esm"
-import { getLocalizedUrl, Locales } from "intlayer";
-
-getLocalizedUrl(
-  "/about",
-  Locales.FRENCH,
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-
-// الناتج: "/fr/about" للغة الفرنسية
-// الناتج: "/about" للغة الافتراضية (الإنجليزية)
-```
-
-```javascript codeFormat="commonjs"
-const { getLocalizedUrl, Locales } = require("intlayer");
-
-getLocalizedUrl(
-  "/about",
-  Locales.FRENCH,
-  [Locales.ENGLISH, Locales.FRENCH],
-  Locales.ENGLISH,
-  false
-);
-
-// الناتج: "/fr/about" للغة الفرنسية
-// الناتج: "/about" للغة الافتراضية (الإنجليزية)
-```
-
 ### تجاوز الإعدادات الجزئية
 
 يمكنك أيضًا توفير بعض المعاملات الاختيارية فقط. ستستخدم الدالة إعدادات مشروعك لأي معاملات لم تحددها:
@@ -241,6 +219,12 @@ getLocalizedUrl(
 - **اللغات غير المدعومة:**
   - بالنسبة للغات غير المدرجة في `locales`، لا تطبق الدالة أي بادئة.
 
+- **أنماط التوجيه:**
+  - `'prefix-no-default'`: اللغة الافتراضية بدون بادئة، والبقية لها بادئات (على سبيل المثال، `/about`, `/fr/about`)
+  - `'prefix-all'`: جميع اللغات لها بادئات (على سبيل المثال، `/en/about`, `/fr/about`)
+  - `'no-prefix'`: لا توجد بادئات لغة في عناوين URL (يتم التعامل مع اللغة في مكان آخر)
+  - `'search-params'`: يتم تحديد اللغة عبر معامل الاستعلام (على سبيل المثال، `/about?locale=fr`)
+
 ---
 
 ## الاستخدام في التطبيقات