@intlayer/docs 5.5.8

package/ar/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# التوثيق: وظيفة `getConfiguration` في `intlayer`
+
+## الوصف
+
+وظيفة `getConfiguration` تسترجع التكوين الكامل لتطبيق `intlayer` عن طريق استخراج متغيرات البيئة. توفر هذه الوظيفة المرونة لاستخدام نفس التكوين على جانبي العميل والخادم، مما يضمن التناسق عبر التطبيق.
+
+---
+
+## المعلمات
+
+لا تأخذ الوظيفة أي معلمات. بدلاً من ذلك، تستخدم متغيرات البيئة للتكوين.
+
+### الإرجاع
+
+- **النوع**: `IntlayerConfig`
+- **الوصف**: كائن يحتوي على التكوين الكامل لـ `intlayer`. يشمل التكوين الأقسام التالية:
+
+  - `internationalization`: الإعدادات المتعلقة باللغات ووضع الصرامة.
+  - `middleware`: الإعدادات المتعلقة بإدارة الروابط وملفات تعريف الارتباط.
+  - `content`: الإعدادات المتعلقة بملفات المحتوى، الأدلة، والأنماط.
+  - `editor`: التكوينات الخاصة بالمحرر.
+
+راجع [توثيق تكوين Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/ar/configuration.md) لمزيد من التفاصيل.
+
+---
+
+## مثال على الاستخدام
+
+### استرجاع التكوين الكامل
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// الإخراج:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// الإخراج:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// الإخراج:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### استخراج `availableLocales` و `defaultLocale`
+
+يوفر قسم `internationalization` من التكوين إعدادات متعلقة باللغات مثل `locales` (اللغات المتاحة) و `defaultLocale` (اللغة الافتراضية).
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // مثال على الإخراج: ["en", "fr", "es"]
+console.log(defaultLocale); // مثال على الإخراج: "en"
+console.log(cookieName); // الإخراج: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // مثال على الإخراج: ["en", "fr", "es"]
+console.log(defaultLocale); // مثال على الإخراج: "en"
+console.log(cookieName); // الإخراج: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // مثال على الإخراج: ["en", "fr", "es"]
+console.log(defaultLocale); // مثال على الإخراج: "en"
+console.log(cookieName); // الإخراج: "INTLAYER_LOCALE"
+```
+
+## ملاحظات
+
+- تأكد من تعيين جميع متغيرات البيئة المطلوبة بشكل صحيح قبل استدعاء هذه الوظيفة. ستتسبب المتغيرات المفقودة في حدوث أخطاء أثناء التهيئة.
+- يمكن استخدام هذه الوظيفة على جانبي العميل والخادم، مما يجعلها أداة متعددة الاستخدامات لإدارة التكوينات بطريقة موحدة.
+
+## الاستخدام في التطبيقات
+
+وظيفة `getConfiguration` هي أداة أساسية لتهيئة وإدارة تكوين تطبيق `intlayer`. من خلال توفير الوصول إلى إعدادات مثل اللغات، الوسيط، وأدلة المحتوى، تضمن التناسق والقابلية للتوسع عبر التطبيقات متعددة اللغات والمحتوى.

package/ar/packages/intlayer/getEnumeration.md

@@ -0,0 +1,138 @@
+# التوثيق: وظيفة `getEnumeration` في `intlayer`
+
+## الوصف
+
+تقوم وظيفة `getEnumeration` باسترجاع المحتوى الذي يتوافق مع كمية معينة بناءً على شروط محددة مسبقًا في كائن التعداد. يتم تعريف الشروط كمفاتيح، ويتم تحديد أولويتها بناءً على ترتيبها في الكائن.
+
+## المعاملات
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **الوصف**: كائن حيث تمثل المفاتيح الشروط (مثل `<=`, `<`, `>=`, `=`) وتمثل القيم المحتوى المقابل. يحدد ترتيب المفاتيح أولوية المطابقة.
+  - **النوع**: `QuantityContent<Content>`
+    - يمكن أن يكون `Content` أي نوع.
+
+- `quantity: number`
+
+  - **الوصف**: القيمة العددية المستخدمة للمطابقة مع الشروط في `enumerationContent`.
+  - **النوع**: `number`
+
+## الإرجاع
+
+- **النوع**: `Content`
+- **الوصف**: المحتوى الذي يتوافق مع أول شرط مطابق في `enumerationContent`. إذا لم يتم العثور على تطابق، فإنه يتم التعامل مع ذلك بناءً على التنفيذ (مثل الخطأ أو محتوى افتراضي).
+
+## مثال على الاستخدام
+
+### الاستخدام الأساسي
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "لديك أقل من -2.3",
+    "<1": "لديك أقل من واحد",
+    "2": "لديك اثنان",
+    ">=3": "لديك ثلاثة أو أكثر",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك اثنان"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "لديك أقل من واحد",
+    "2": "لديك اثنان",
+    ">=3": "لديك ثلاثة أو أكثر",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك اثنان"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "لديك أقل من واحد",
+    "2": "لديك اثنان",
+    ">=3": "لديك ثلاثة أو أكثر",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك اثنان"
+```
+
+### أولوية الشروط
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "لديك أقل من أربعة",
+    "2": "لديك اثنان",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك أقل من أربعة"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "لديك أقل من أربعة",
+    "2": "لديك اثنان",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك أقل من أربعة"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "لديك أقل من أربعة",
+    "2": "لديك اثنان",
+  },
+  2
+);
+
+console.log(content); // الناتج: "لديك أقل من أربعة"
+```
+
+## الحالات الخاصة
+
+- **عدم وجود شرط مطابق:**
+
+  - إذا لم يتطابق أي شرط مع الكمية المقدمة، فإن الوظيفة ستعيد إما `undefined` أو تتعامل مع السيناريو الافتراضي بشكل صريح.
+
+- **الشروط الغامضة:**
+
+  - إذا كانت الشروط متداخلة، فإن أول شرط مطابق (بناءً على ترتيب الكائن) له الأولوية.
+
+- **المفاتيح غير الصالحة:**
+
+  - تفترض الوظيفة أن جميع المفاتيح في `enumerationContent` صالحة وقابلة للتحليل كشرط. قد تؤدي المفاتيح غير الصالحة أو ذات التنسيق غير الصحيح إلى سلوك غير متوقع.
+
+- **التطبيق في TypeScript:**
+  - تضمن الوظيفة أن نوع `Content` متسق عبر جميع المفاتيح، مما يسمح بالأمان النوعي في المحتوى المسترجع.
+
+## ملاحظات
+
+- يتم استخدام أداة `findMatchingCondition` لتحديد الشرط المناسب بناءً على الكمية المعطاة.

package/ar/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# التوثيق: وظيفة `getHTMLTextDir` في `intlayer`
+
+## الوصف
+
+تحدد وظيفة `getHTMLTextDir` اتجاه النص (`ltr`, `rtl`, أو `auto`) بناءً على اللغة المحددة. تم تصميمها لمساعدة المطورين على تعيين خاصية `dir` في HTML لعرض النصوص بشكل صحيح.
+
+## المعاملات
+
+- `locale?: Locales`
+
+  - **الوصف**: سلسلة اللغة (مثلًا، `Locales.ENGLISH`, `Locales.ARABIC`) المستخدمة لتحديد اتجاه النص.
+  - **النوع**: `Locales` (اختياري)
+
+## القيم المعادة
+
+- **النوع**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **الوصف**: اتجاه النص الذي يتوافق مع اللغة:
+  - `'ltr'` للغات التي تكتب من اليسار إلى اليمين.
+  - `'rtl'` للغات التي تكتب من اليمين إلى اليسار.
+  - `'auto'` إذا لم يتم التعرف على اللغة.
+
+## مثال على الاستخدام
+
+### تحديد اتجاه النص
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // الناتج: "ltr"
+getHTMLTextDir(Locales.FRENCH); // الناتج: "ltr"
+getHTMLTextDir(Locales.ARABIC); // الناتج: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // الناتج: "ltr"
+getHTMLTextDir(Locales.FRENCH); // الناتج: "ltr"
+getHTMLTextDir(Locales.ARABIC); // الناتج: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // الناتج: "ltr"
+getHTMLTextDir(Locales.FRENCH); // الناتج: "ltr"
+getHTMLTextDir(Locales.ARABIC); // الناتج: "rtl"
+```
+
+## الحالات الخاصة
+
+- **عدم توفير لغة:**
+
+  - تعيد الوظيفة `'auto'` عندما تكون `locale` غير معرفة.
+
+- **لغة غير معروفة:**
+  - بالنسبة للغات غير المعروفة، تقوم الوظيفة بالافتراض إلى `'auto'`.
+
+## الاستخدام في المكونات:
+
+يمكن استخدام وظيفة `getHTMLTextDir` لتعيين خاصية `dir` بشكل ديناميكي في مستند HTML لعرض النصوص بشكل صحيح بناءً على اللغة.
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+في المثال أعلاه، يتم تعيين خاصية `dir` بشكل ديناميكي بناءً على اللغة.

package/ar/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,61 @@
+To translate this file into Arabic (العربية):
+
+# التوثيق: وظيفة `getLocaleLang` في `intlayer`
+
+## الوصف
+
+وظيفة `getLocaleLang` تستخرج رمز اللغة من سلسلة اللغة المحلية. تدعم اللغات المحلية مع أو بدون رموز الدول. إذا لم يتم توفير لغة محلية، فإنها تعود افتراضياً بسلسلة فارغة.
+
+## المعلمات
+
+- `locale?: Locales`
+
+  - **الوصف**: سلسلة اللغة المحلية (على سبيل المثال، `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`) التي يتم استخراج رمز اللغة منها.
+  - **النوع**: `Locales` (اختياري)
+
+## الإرجاع
+
+- **النوع**: `string`
+- **الوصف**: رمز اللغة المستخرج من اللغة المحلية. إذا لم يتم توفير اللغة المحلية، فإنه يعود بسلسلة فارغة (`''`).
+
+## مثال على الاستخدام
+
+### استخراج رموز اللغات:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // الناتج: "en"
+getLocaleLang(Locales.ENGLISH); // الناتج: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // الناتج: "fr"
+getLocaleLang(Locales.FRENCH); // الناتج: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // الناتج: "en"
+getLocaleLang(Locales.ENGLISH); // الناتج: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // الناتج: "fr"
+getLocaleLang(Locales.FRENCH); // الناتج: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // الناتج: "en"
+getLocaleLang(Locales.ENGLISH); // الناتج: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // الناتج: "fr"
+getLocaleLang(Locales.FRENCH); // الناتج: "fr"
+```
+
+## الحالات الخاصة
+
+- **عدم توفير لغة محلية:**
+
+  - تعود الوظيفة بسلسلة فارغة عندما تكون `locale` غير معرفة.
+
+- **سلاسل لغة محلية غير صحيحة:**
+  - إذا لم تتبع `locale` تنسيق `language-country` (على سبيل المثال، `Locales.ENGLISH-US`)، فإن الوظيفة تعود بأمان بالجزء قبل `'-'` أو السلسلة الكاملة إذا لم يكن هناك `'-'`.
+
+[رابط التوثيق](https://github.com/aymericzip/intlayer/blob/main/docs/ar/**/*.md)

package/ar/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# وثائق: وظيفة `getLocaleName` في `intlayer`
+
+## الوصف
+
+وظيفة `getLocaleName` تُرجع الاسم المحلي للغة معينة (`targetLocale`) في لغة العرض (`displayLocale`). إذا لم يتم توفير `targetLocale`، فإنها تُرجع اسم `displayLocale` بلغته الخاصة.
+
+## المعاملات
+
+- `displayLocale: Locales`
+
+  - **الوصف**: اللغة التي سيتم عرض اسم اللغة المستهدفة بها.
+  - **النوع**: Enum أو سلسلة نصية تمثل لغات صالحة.
+
+- `targetLocale?: Locales`
+  - **الوصف**: اللغة التي سيتم توطين اسمها.
+  - **النوع**: اختياري. Enum أو سلسلة نصية تمثل لغات صالحة.
+
+## القيم المُعادة
+
+- **النوع**: `string`
+- **الوصف**: الاسم المحلي لـ `targetLocale` في `displayLocale`، أو اسم `displayLocale` الخاص إذا لم يتم توفير `targetLocale`. إذا لم يتم العثور على ترجمة، فإنها تُرجع `"لغة غير معروفة"`.
+
+## أمثلة الاستخدام
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // الناتج: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // الناتج: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // الناتج: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // الناتج: "English"
+
+getLocaleName(Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // الناتج: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // الناتج: "French"
+
+getLocaleName(Locales.CHINESE); // الناتج: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // الناتج: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // الناتج: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // الناتج: "Chinese"
+
+getLocaleName("unknown-locale"); // الناتج: "لغة غير معروفة"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // الناتج: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // الناتج: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // الناتج: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // الناتج: "English"
+
+getLocaleName(Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // الناتج: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // الناتج: "French"
+
+getLocaleName(Locales.CHINESE); // الناتج: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // الناتج: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // الناتج: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // الناتج: "Chinese"
+
+getLocaleName("unknown-locale"); // الناتج: "لغة غير معروفة"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // الناتج: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // الناتج: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // الناتج: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // الناتج: "English"
+
+getLocaleName(Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // الناتج: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // الناتج: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // الناتج: "French"
+
+getLocaleName(Locales.CHINESE); // الناتج: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // الناتج: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // الناتج: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // الناتج: "Chinese"
+
+getLocaleName("unknown-locale"); // الناتج: "لغة غير معروفة"
+```
+
+## الحالات الخاصة
+
+- **عدم توفير `targetLocale`:**
+  - تقوم الوظيفة افتراضيًا بإرجاع اسم `displayLocale` الخاص.
+- **الترجمات المفقودة:**
+  - إذا لم يحتوي `localeNameTranslations` على إدخال لـ `targetLocale` أو `displayLocale` المحدد، فإن الوظيفة تعود إلى `ownLocalesName` أو تُرجع `"لغة غير معروفة"`.