@intlayer/docs 5.5.8

package/ar/intlayer_with_create_react_app.md

@@ -0,0 +1,1196 @@
+# البدء في التدويل (i18n) باستخدام Intlayer و React Create App
+
+انظر [Application Template](https://github.com/aymericzip/intlayer-react-cra-template) على GitHub.
+
+## ما هو Intlayer؟
+
+**Intlayer** هو مكتبة مفتوحة المصدر مبتكرة للتدويل (i18n) مصممة لتبسيط دعم اللغات المتعددة في تطبيقات الويب الحديثة.
+
+مع Intlayer، يمكنك:
+
+- **إدارة الترجمات بسهولة** باستخدام قواميس تصريحية على مستوى المكونات.
+- **توطين البيانات الوصفية والمسارات والمحتوى ديناميكيًا**.
+- **ضمان دعم TypeScript** مع الأنواع المولدة تلقائيًا، مما يحسن الإكمال التلقائي واكتشاف الأخطاء.
+- **الاستفادة من الميزات المتقدمة**، مثل اكتشاف اللغة الديناميكي والتبديل.
+
+## دليل خطوة بخطوة لإعداد Intlayer في تطبيق React
+
+### الخطوة 1: تثبيت التبعيات
+
+قم بتثبيت الحزم الضرورية باستخدام npm:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer react-scripts-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer react-scripts-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer react-intlayer react-scripts-intlayer
+```
+
+- **intlayer**
+
+  الحزمة الأساسية التي توفر أدوات التدويل لإدارة التكوين، الترجمة، [إعلان المحتوى](https://github.com/aymericzip/intlayer/blob/main/docs/ar/dictionary/get_started.md)، الترجمة، و[أوامر CLI](https://github.com/aymericzip/intlayer/blob/main/docs/ar/intlayer_cli.md).
+
+- **react-intlayer**
+
+  الحزمة التي تدمج Intlayer مع تطبيق React. توفر موفري السياق وخطافات لتدويل React.
+
+- **react-scripts-intlayer**
+
+  تتضمن أوامر ومكونات `react-scripts-intlayer` لتكامل Intlayer مع تطبيق يعتمد على Create React App. تعتمد هذه المكونات على [craco](https://craco.js.org/) وتتضمن تكوينًا إضافيًا لمجمع [Webpack](https://webpack.js.org/).
+
+### الخطوة 2: تكوين مشروعك
+
+قم بإنشاء ملف تكوين لتحديد لغات تطبيقك:
+
+```typescript fileName="intlayer.config.ts"  codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // لغاتك الأخرى
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // لغاتك الأخرى
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // لغاتك الأخرى
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> من خلال ملف التكوين هذا، يمكنك إعداد عناوين URL المحلية، إعادة التوجيه عبر الوسيط، أسماء ملفات تعريف الارتباط، موقع وامتداد إعلانات المحتوى الخاصة بك، تعطيل سجلات Intlayer في وحدة التحكم، والمزيد. للحصول على قائمة كاملة بالمعلمات المتاحة، راجع [وثائق التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/ar/configuration.md).
+
+### الخطوة 3: دمج Intlayer في تكوين CRA الخاص بك
+
+قم بتغيير السكربتات لاستخدام react-intlayer
+
+```json fileName="package.json"
+  "scripts": {
+    "build": "react-scripts-intlayer build",
+    "start": "react-scripts-intlayer start",
+    "transpile": "intlayer build"
+  },
+```
+
+> تعتمد سكربتات `react-scripts-intlayer` على [CRACO](https://craco.js.org/). يمكنك أيضًا تنفيذ إعدادك الخاص بناءً على مكون intlayer craco. [انظر المثال هنا](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+
+### الخطوة 4: إعلان المحتوى الخاص بك
+
+قم بإنشاء وإدارة إعلانات المحتوى الخاصة بك لتخزين الترجمات:
+
+```tsx fileName="src/app.content.tsx" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+import React, { type ReactNode } from "react";
+
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t<ReactNode>({
+      ar: (
+        <>
+          قم بتحرير <code>src/App.tsx</code> واحفظ لإعادة التحميل
+        </>
+      ),
+      en: (
+        <>
+          Edit <code>src/App.tsx</code> and save to reload
+        </>
+      ),
+      fr: (
+        <>
+          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
+        </>
+      ),
+      es: (
+        <>
+          Edita <code>src/App.tsx</code> y guarda para recargar
+        </>
+      ),
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        ar: "تعلم React",
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+      }),
+    },
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```jsx fileName="src/app.content.mjx" codeFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t({
+      ar: "ابدأ بتحرير",
+      en: "Get started by editing",
+      fr: "Commencez par éditer",
+      es: "Comience por editar",
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        ar: "تعلم React",
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+      }),
+    },
+  },
+};
+
+export default appContent;
+```
+
+```jsx fileName="src/app.content.csx" codeFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t({
+      ar: "ابدأ بتحرير",
+      en: "Get started by editing",
+      fr: "Commencez par éditer",
+      es: "Comience por editar",
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        ar: "تعلم React",
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+      }),
+    },
+  },
+};
+
+module.exports = appContent;
+```
+
+> يمكن تعريف إعلانات المحتوى الخاصة بك في أي مكان في تطبيقك طالما تم تضمينها في دليل `contentDir` (افتراضيًا، `./src`). وتطابق امتداد ملف إعلان المحتوى (افتراضيًا، `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+
+> لمزيد من التفاصيل، راجع [وثائق إعلان المحتوى](https://github.com/aymericzip/intlayer/blob/main/docs/ar/dictionary/get_started.md).
+
+> إذا كان ملف المحتوى الخاص بك يتضمن كود TSX، يجب أن تفكر في استيراد `import React from "react";` في ملف المحتوى الخاص بك.
+
+### الخطوة 5: استخدام Intlayer في الكود الخاص بك
+
+الوصول إلى قواميس المحتوى الخاصة بك في جميع أنحاء تطبيقك:
+
+```tsx {4,7} fileName="src/App.tsx"  codeFormat="typescript"
+import logo from "./logo.svg";
+import "./App.css";
+import type { FC } from "react";
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+
+const AppContent: FC = () => {
+  const content = useIntlayer("app");
+
+  return (
+    <div className="App">
+      <img src={logo} className="App-logo" alt="logo" />
+
+      {content.getStarted}
+      <a
+        className="App-link"
+        href={content.reactLink.href.value}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {content.reactLink.content}
+      </a>
+    </div>
+  );
+};
+
+const App: FC = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```jsx {3,6} fileName="src/App.mjx" codeFormat="esm"
+import "./App.css";
+import logo from "./logo.svg";
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+
+const AppContent = () => {
+  const content = useIntlayer("app");
+
+  return (
+    <div className="App">
+      <img src={logo} className="App-logo" alt="logo" />
+
+      {content.getStarted}
+      <a
+        className="App-link"
+        href={content.reactLink.href.value}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {content.reactLink.content}
+      </a>
+    </div>
+  );
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+require("./App.css");
+const logo = require("./logo.svg");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+
+const AppContent = () => {
+  const content = useIntlayer("app");
+
+  return (
+    <div className="App">
+      <img src={logo} className="App-logo" alt="الشعار" />
+
+      {content.getStarted}
+      <a
+        className="App-link"
+        href={content.reactLink.href.value}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {content.reactLink.content}
+      </a>
+    </div>
+  );
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+```
+
+> ملاحظة: إذا كنت ترغب في استخدام المحتوى الخاص بك في سمة `string`، مثل `alt`، `title`، `href`، `aria-label`، وما إلى ذلك، يجب عليك استدعاء قيمة الوظيفة، مثل:
+
+> ```jsx
+>
+> ```
+
+> <img src={content.image.src.value} alt={content.image.value} />
+
+> ```
+>
+> ```
+
+> لمعرفة المزيد عن الخطاف `useIntlayer`، راجع [التوثيق](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/react-intlayer/useIntlayer.md).
+
+### (اختياري) الخطوة 6: تغيير لغة المحتوى الخاص بك
+
+لتغيير لغة المحتوى الخاص بك، يمكنك استخدام وظيفة `setLocale` المقدمة من الخطاف `useLocale`. تتيح لك هذه الوظيفة تعيين اللغة للتطبيق وتحديث المحتوى وفقًا لذلك.
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import { Locales } from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { setLocale } = useLocale();
+
+  return (
+    <button onClick={() => setLocale(Locales.English)}>
+      تغيير اللغة إلى الإنجليزية
+    </button>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { Locales } from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { setLocale } = useLocale();
+
+  return (
+    <button onClick={() => setLocale(Locales.English)}>
+      تغيير اللغة إلى الإنجليزية
+    </button>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { setLocale } = useLocale();
+
+  return (
+    <button onClick={() => setLocale(Locales.English)}>
+      تغيير اللغة إلى الإنجليزية
+    </button>
+  );
+};
+```
+
+> لمعرفة المزيد عن الخطاف `useLocale`، راجع [التوثيق](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/react-intlayer/useLocale.md).
+
+### (اختياري) الخطوة 7: إضافة التوجيه المحلي إلى تطبيقك
+
+الغرض من هذه الخطوة هو إنشاء مسارات فريدة لكل لغة. هذا مفيد لتحسين محركات البحث (SEO) وعناوين URL الصديقة لمحركات البحث.
+مثال:
+
+```plaintext
+- https://example.com/about
+- https://example.com/es/about
+- https://example.com/fr/about
+```
+
+> بشكل افتراضي، لا يتم تفضيل المسارات للغة الافتراضية. إذا كنت ترغب في تفضيل اللغة الافتراضية، يمكنك تعيين الخيار `middleware.prefixDefault` إلى `true` في التكوين الخاص بك. راجع [توثيق التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/ar/configuration.md) لمزيد من المعلومات.
+
+لإضافة التوجيه المحلي إلى تطبيقك، يمكنك إنشاء مكون `LocaleRouter` الذي يلتف حول مسارات التطبيق الخاصة بك ويتعامل مع التوجيه المستند إلى اللغة. فيما يلي مثال باستخدام [React Router](https://reactrouter.com/home):
+
+```tsx fileName="src/components/LocaleRouter.tsx"  codeFormat="typescript"
+// استيراد التبعيات والوظائف اللازمة
+import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // وظائف وأدوات من 'intlayer'
+import type { FC, PropsWithChildren } from "react"; // أنواع React للمكونات الوظيفية والخصائص
+import { IntlayerProvider } from "react-intlayer"; // مزود لسياق التدويل
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} from "react-router-dom"; // مكونات التوجيه لإدارة التنقل
+
+// استخراج التكوين من Intlayer
+const { internationalization, middleware } = configuration;
+const { locales, defaultLocale } = internationalization;
+
+/**
+ * مكون يتعامل مع التوطين ويلتف حول الأطفال بسياق اللغة المناسب.
+ * يدير الكشف عن اللغة المستندة إلى عنوان URL والتحقق من صحتها.
+ */
+const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي
+
+  // تحديد اللغة الحالية، مع الرجوع إلى الافتراضية إذا لم يتم توفيرها
+  const currentLocale = locale ?? defaultLocale;
+
+  // إزالة بادئة اللغة من المسار لإنشاء مسار أساسي
+  const pathWithoutLocale = getPathWithoutLocale(
+    pathname // مسار URL الحالي
+  );
+
+  /**
+   * إذا كانت middleware.prefixDefault تساوي true، يجب دائمًا تفضيل اللغة الافتراضية.
+   */
+  if (middleware.prefixDefault) {
+    // التحقق من صحة اللغة
+    if (!locale || !locales.includes(locale)) {
+      // إعادة التوجيه إلى اللغة الافتراضية مع المسار المحدث
+      return (
+        <Navigate
+          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
+          replace // استبدال الإدخال الحالي في السجل بالإدخال الجديد
+        />
+      );
+    }
+
+    // التفاف الأطفال مع IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  } else {
+    /**
+     * عندما تكون middleware.prefixDefault تساوي false، لا يتم تفضيل اللغة الافتراضية.
+     * تأكد من أن اللغة الحالية صالحة وليست اللغة الافتراضية.
+     */
+    if (
+      currentLocale.toString() !== defaultLocale.toString() &&
+      !locales
+        .filter(
+          (locale) => locale.toString() !== defaultLocale.toString() // استبعاد اللغة الافتراضية
+        )
+        .includes(currentLocale) // التحقق مما إذا كانت اللغة الحالية موجودة في قائمة اللغات الصالحة
+    ) {
+      // إعادة التوجيه إلى المسار بدون بادئة اللغة
+      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
+    }
+
+    // التفاف الأطفال مع IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  }
+};
+
+/**
+ * مكون التوجيه الذي يقوم بإعداد المسارات الخاصة باللغة.
+ * يستخدم React Router لإدارة التنقل وعرض المكونات المحلية.
+ */
+export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
+  <BrowserRouter>
+    <Routes>
+      {locales
+        .filter(
+          (locale) => middleware.prefixDefault || locale !== defaultLocale
+        )
+        .map((locale) => (
+          <Route
+            // نمط المسار لالتقاط اللغة (مثل /en/، /fr/) ومطابقة جميع المسارات اللاحقة
+            path={`/${locale}/*`}
+            key={locale}
+            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // يلتف حول الأطفال مع إدارة اللغة
+          />
+        ))}
+
+      {
+        // إذا تم تعطيل تفضيل اللغة الافتراضية، قم بعرض الأطفال مباشرة في المسار الجذر
+        !middleware.prefixDefault && (
+          <Route
+            path="*"
+            element={
+              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
+            } // يلتف حول الأطفال مع إدارة اللغة
+          />
+        )
+      }
+    </Routes>
+  </BrowserRouter>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.mjx" codeFormat="esm"
+// استيراد التبعيات والوظائف اللازمة
+import { configuration, getPathWithoutLocale } from "intlayer"; // وظائف وأدوات من 'intlayer'
+import { IntlayerProvider } from "react-intlayer"; // مزود لسياق التدويل
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} from "react-router-dom"; // مكونات التوجيه لإدارة التنقل
+
+// استيراد التكوين من Intlayer
+const { internationalization, middleware } = configuration;
+const { locales, defaultLocale } = internationalization;
+
+/**
+ * مكون يتعامل مع التوطين ويغلف العناصر الفرعية بسياق اللغة المناسب.
+ * يدير الكشف عن اللغة والتحقق منها بناءً على عنوان URL.
+ */
+const AppLocalized = ({ children, locale }) => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي
+
+  // تحديد اللغة الحالية، مع الرجوع إلى اللغة الافتراضية إذا لم يتم توفيرها
+  const currentLocale = locale ?? defaultLocale;
+
+  // إزالة بادئة اللغة من المسار لإنشاء مسار أساسي
+  const pathWithoutLocale = getPathWithoutLocale(
+    pathname // مسار URL الحالي
+  );
+
+  /**
+   * إذا كانت middleware.prefixDefault صحيحة، يجب دائمًا أن تكون اللغة الافتراضية مسبوقة.
+   */
+  if (middleware.prefixDefault) {
+    // التحقق من صحة اللغة
+    if (!locale || !locales.includes(locale)) {
+      // إعادة التوجيه إلى اللغة الافتراضية مع المسار المحدث
+      return (
+        <Navigate
+          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
+          replace // استبدال الإدخال الحالي في السجل بالإدخال الجديد
+        />
+      );
+    }
+
+    // تغليف العناصر الفرعية بـ IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  } else {
+    /**
+     * عندما تكون middleware.prefixDefault خاطئة، لا يتم إضافة بادئة للغة الافتراضية.
+     * تأكد من أن اللغة الحالية صالحة وليست اللغة الافتراضية.
+     */
+    if (
+      currentLocale.toString() !== defaultLocale.toString() &&
+      !locales
+        .filter(
+          (locale) => locale.toString() !== defaultLocale.toString() // استبعاد اللغة الافتراضية
+        )
+        .includes(currentLocale) // تحقق إذا كانت اللغة الحالية ضمن قائمة اللغات الصالحة
+    ) {
+      // إعادة التوجيه إلى المسار بدون بادئة اللغة
+      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
+    }
+
+    // تغليف العناصر الفرعية بـ IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  }
+};
+
+/**
+ * مكون موجه يقوم بإعداد مسارات مخصصة للغات.
+ * يستخدم React Router لإدارة التنقل وعرض المكونات الموطنة.
+ */
+export const LocaleRouter = ({ children }) => (
+  <BrowserRouter>
+    <Routes>
+      {locales
+        .filter(
+          (locale) => middleware.prefixDefault || locale !== defaultLocale
+        )
+        .map((locale) => (
+          <Route
+            // نمط المسار لالتقاط اللغة (مثل /en/, /fr/) ومطابقة جميع المسارات اللاحقة
+            path={`/${locale}/*`}
+            key={locale}
+            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // يغلف العناصر الفرعية بإدارة اللغة
+          />
+        ))}
+
+      {
+        // إذا تم تعطيل إضافة بادئة للغة الافتراضية، قم بعرض العناصر الفرعية مباشرة في المسار الجذر
+        !middleware.prefixDefault && (
+          <Route
+            path="*"
+            element={
+              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
+            } // يغلف العناصر الفرعية بإدارة اللغة
+          />
+        )
+      }
+    </Routes>
+  </BrowserRouter>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.cjx" codeFormat="commonjs"
+// استيراد التبعيات والوظائف اللازمة
+const { configuration, getPathWithoutLocale } = require("intlayer"); // وظائف وأدوات مساعدة من 'intlayer'
+const { IntlayerProvider, useLocale } = require("react-intlayer"); // موفر لسياق التوطين
+const {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} = require("react-router-dom"); // مكونات الموجه لإدارة التنقل
+
+// استيراد التكوين من Intlayer
+const { internationalization, middleware } = configuration;
+const { locales, defaultLocale } = internationalization;
+
+/**
+ * مكون يتعامل مع التوطين ويغلف العناصر الفرعية بسياق اللغة المناسب.
+ * يدير الكشف عن اللغة والتحقق منها بناءً على عنوان URL.
+ */
+const AppLocalized = ({ children, locale }) => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي
+
+  // تحديد اللغة الحالية، مع الرجوع إلى اللغة الافتراضية إذا لم يتم توفيرها
+  const currentLocale = locale ?? defaultLocale;
+
+  // إزالة بادئة اللغة من المسار لإنشاء مسار أساسي
+  const pathWithoutLocale = getPathWithoutLocale(
+    pathname // مسار URL الحالي
+  );
+
+  /**
+   * إذا كانت middleware.prefixDefault صحيحة، يجب دائمًا أن تكون اللغة الافتراضية مسبوقة.
+   */
+  if (middleware.prefixDefault) {
+    // التحقق من صحة اللغة
+    if (!locale || !locales.includes(locale)) {
+      // إعادة التوجيه إلى اللغة الافتراضية مع المسار المحدث
+      return (
+        <Navigate
+          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
+          replace // استبدال الإدخال الحالي في السجل بالإدخال الجديد
+        />
+      );
+    }
+
+    // تغليف العناصر الفرعية بـ IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  } else {
+    /**
+     * عندما تكون middleware.prefixDefault خاطئة، لا يتم إضافة بادئة للغة الافتراضية.
+     * تأكد من أن اللغة الحالية صالحة وليست اللغة الافتراضية.
+     */
+    if (
+      currentLocale.toString() !== defaultLocale.toString() &&
+      !locales
+        .filter(
+          (locale) => locale.toString() !== defaultLocale.toString() // استبعاد اللغة الافتراضية
+        )
+        .includes(currentLocale) // تحقق إذا كانت اللغة الحالية ضمن قائمة اللغات الصالحة
+    ) {
+      // إعادة التوجيه إلى المسار بدون بادئة اللغة
+      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
+    }
+
+    // تغليف العناصر الفرعية بـ IntlayerProvider وتعيين اللغة الحالية
+    return (
+      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
+    );
+  }
+};
+
+/**
+ * مكون موجه يقوم بإعداد مسارات مخصصة للغات.
+ * يستخدم React Router لإدارة التنقل وعرض المكونات الموطنة.
+ */
+const LocaleRouter = ({ children }) => (
+  <BrowserRouter>
+    <Routes>
+      {locales
+        .filter(
+          (locale) => middleware.prefixDefault || locale !== defaultLocale
+        )
+        .map((locale) => (
+          <Route
+            // نمط المسار لالتقاط اللغة (مثل /en/, /fr/) ومطابقة جميع المسارات اللاحقة
+            path={`/${locale}/*`}
+            key={locale}
+            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // يغلف العناصر الفرعية بإدارة اللغة
+          />
+        ))}
+
+      {
+        // إذا تم تعطيل إضافة بادئة للغة الافتراضية، قم بعرض العناصر الفرعية مباشرة في المسار الجذر
+        !middleware.prefixDefault && (
+          <Route
+            path="*"
+            element={
+              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
+            } // يغلف العناصر الفرعية بإدارة اللغة
+          />
+        )
+      }
+    </Routes>
+  </BrowserRouter>
+);
+```
+
+ثم يمكنك استخدام مكون `LocaleRouter` في تطبيقك:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import { LocaleRouter } from "./components/LocaleRouter";
+import type { FC } from "react";
+
+// ... مكون AppContent الخاص بك
+
+const App: FC = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.mjx" codeFormat="esm"
+import { LocaleRouter } from "./components/LocaleRouter";
+
+// ... مكون AppContent الخاص بك
+
+const App = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.cjx" codeFormat="commonjs"
+const { LocaleRouter } = require("./components/LocaleRouter");
+
+// ... مكون AppContent الخاص بك
+
+const App = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+### (اختياري) الخطوة 8: تغيير عنوان URL عند تغيير اللغة
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import { useLocation, useNavigate } from "react-router-dom";
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocale } from "react-intlayer";
+import { type FC } from "react";
+
+const LocaleSwitcher: FC = () => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي. مثال: /fr/about?foo=bar
+  const navigate = useNavigate();
+
+  const { locale, availableLocales, setLocale } = useLocale({
+    onLocaleChange: (locale) => {
+      // إنشاء عنوان URL مع اللغة المحلية المحدثة
+      // مثال: /es/about?foo=bar
+      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);
+
+      // تحديث مسار URL
+      navigate(pathWithLocale);
+    },
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <a
+            href={getLocalizedUrl(location.pathname, localeItem)}
+            hrefLang={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={(e) => {
+              e.preventDefault();
+              setLocale(localeItem);
+            }}
+            key={localeItem}
+          >
+            <span>
+              {/* اللغة المحلية - مثال: FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* اللغة في لغتها المحلية - مثال: Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* اللغة في اللغة الحالية - مثال: Francés مع اللغة الحالية المحددة إلى Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* اللغة بالإنجليزية - مثال: French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.msx" codeFormat="esm"
+import { useLocation, useNavigate } from "react-router-dom";
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي. مثال: /fr/about?foo=bar
+  const navigate = useNavigate();
+
+  const { locale, availableLocales, setLocale } = useLocale({
+    onLocaleChange: (locale) => {
+      // إنشاء عنوان URL مع اللغة المحلية المحدثة
+      // مثال: /es/about?foo=bar
+      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);
+
+      // تحديث مسار URL
+      navigate(pathWithLocale);
+    },
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <a
+            href={getLocalizedUrl(location.pathname, localeItem)}
+            hrefLang={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={(e) => {
+              e.preventDefault();
+              setLocale(localeItem);
+            }}
+            key={localeItem}
+          >
+            <span>
+              {/* اللغة المحلية - مثال: FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* اللغة في لغتها المحلية - مثال: Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* اللغة في اللغة الحالية - مثال: Francés مع اللغة الحالية المحددة إلى Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* اللغة بالإنجليزية - مثال: French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocation, useNavigate } = require("react-router-dom");
+const {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} = require("intlayer");
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { pathname, search } = useLocation(); // الحصول على مسار URL الحالي. مثال: /fr/about?foo=bar
+  const navigate = useNavigate();
+
+  const { locale, availableLocales, setLocale } = useLocale({
+    onLocaleChange: (locale) => {
+      // إنشاء عنوان URL مع اللغة المحلية المحدثة
+      // مثال: /es/about?foo=bar
+      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);
+
+      // تحديث مسار URL
+      navigate(pathWithLocale);
+    },
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <a
+            href={getLocalizedUrl(location.pathname, localeItem)}
+            hrefLang={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={(e) => {
+              e.preventDefault();
+              setLocale(localeItem);
+            }}
+            key={localeItem}
+          >
+            <span>
+              {/* اللغة المحلية - مثال: FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* اللغة في لغتها المحلية - مثال: Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* اللغة في اللغة الحالية - مثال: Francés مع اللغة الحالية المحددة إلى Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* اللغة بالإنجليزية - مثال: French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+> مراجع التوثيق:
+
+> - [خطاف `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/react-intlayer/useLocale.md)
+
+> - [خطاف `getLocaleName`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/intlayer/getLocaleName.md)
+
+> - [خطاف `getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/intlayer/getLocalizedUrl.md)
+
+> - [خطاف `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/intlayer/getHTMLTextDir.md)
+
+> - [خاصية `hrefLang`](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
+
+> - [خاصية `lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
+
+> - [خاصية `dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
+
+> - [خاصية `aria-current`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
+
+### (اختياري) الخطوة 9: تغيير سمات اللغة والاتجاه في HTML
+
+عندما تدعم تطبيقك لغات متعددة، من الضروري تحديث سمات `lang` و`dir` في علامة `<html>` لتتوافق مع اللغة المحلية الحالية. يضمن ذلك:
+
+- **إمكانية الوصول**: تعتمد قارئات الشاشة والتقنيات المساعدة على السمة الصحيحة `lang` لنطق وتفسير المحتوى بدقة.
+
+من خلال تحديث هذه السمات ديناميكيًا عند تغيير اللغة، تضمن تجربة متسقة وسهلة الوصول للمستخدمين عبر جميع اللغات المدعومة.
+
+#### تنفيذ الخطاف
+
+قم بإنشاء خطاف مخصص لإدارة سمات HTML. يستمع الخطاف لتغييرات اللغة ويقوم بتحديث السمات وفقًا لذلك:
+
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+import { useEffect } from "react";
+import { useLocale } from "react-intlayer";
+import { getHTMLTextDir } from "intlayer";
+
+/**
+ * يقوم بتحديث سمات `lang` و `dir` لعنصر HTML <html> بناءً على اللغة الحالية.
+ * - `lang`: يُعلم المتصفحات ومحركات البحث بلغة الصفحة.
+ * - `dir`: يضمن ترتيب القراءة الصحيح (مثل 'ltr' للإنجليزية، 'rtl' للعربية).
+ *
+ * هذا التحديث الديناميكي ضروري لعرض النصوص بشكل صحيح، وسهولة الوصول، وتحسين محركات البحث.
+ */
+export const useI18nHTMLAttributes = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    // تحديث سمة اللغة إلى اللغة الحالية.
+    document.documentElement.lang = locale;
+
+    // تعيين اتجاه النص بناءً على اللغة الحالية.
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.msx" codeFormat="esm"
+import { useEffect } from "react";
+import { useLocale } from "react-intlayer";
+import { getHTMLTextDir } from "intlayer";
+
+/**
+ * يقوم بتحديث سمات `lang` و `dir` لعنصر HTML <html> بناءً على اللغة الحالية.
+ * - `lang`: يُعلم المتصفحات ومحركات البحث بلغة الصفحة.
+ * - `dir`: يضمن ترتيب القراءة الصحيح (مثل 'ltr' للإنجليزية، 'rtl' للعربية).
+ *
+ * هذا التحديث الديناميكي ضروري لعرض النصوص بشكل صحيح، وسهولة الوصول، وتحسين محركات البحث.
+ */
+export const useI18nHTMLAttributes = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    // تحديث سمة اللغة إلى اللغة الحالية.
+    document.documentElement.lang = locale;
+
+    // تعيين اتجاه النص بناءً على اللغة الحالية.
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.csx" codeFormat="commonjs"
+const { useEffect } = require("react");
+const { useLocale } = require("react-intlayer");
+const { getHTMLTextDir } = require("intlayer");
+
+/**
+ * يقوم بتحديث سمات `lang` و `dir` لعنصر HTML <html> بناءً على اللغة الحالية.
+ * - `lang`: يُعلم المتصفحات ومحركات البحث بلغة الصفحة.
+ * - `dir`: يضمن ترتيب القراءة الصحيح (مثل 'ltr' للإنجليزية، 'rtl' للعربية).
+ *
+ * هذا التحديث الديناميكي ضروري لعرض النصوص بشكل صحيح، وسهولة الوصول، وتحسين محركات البحث.
+ */
+const useI18nHTMLAttributes = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    // تحديث سمة اللغة إلى اللغة الحالية.
+    document.documentElement.lang = locale;
+
+    // تعيين اتجاه النص بناءً على اللغة الحالية.
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+
+module.exports = { useI18nHTMLAttributes };
+```
+
+#### استخدام الخطاف في تطبيقك
+
+قم بدمج الخطاف في المكون الرئيسي الخاص بك بحيث يتم تحديث سمات HTML كلما تغيرت اللغة:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
+import "./App.css";
+
+const AppContent: FC = () => {
+  // تطبيق الخطاف لتحديث سمات lang و dir لعلامة <html> بناءً على اللغة.
+  useI18nHTMLAttributes();
+
+  // ... بقية المكون الخاص بك
+};
+
+const App: FC = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```jsx fileName="src/App.msx" codeFormat="esm"
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
+import "./App.css";
+
+const AppContent = () => {
+  // تطبيق الخطاف لتحديث سمات lang و dir لعلامة <html> بناءً على اللغة.
+  useI18nHTMLAttributes();
+
+  // ... بقية المكون الخاص بك
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```jsx fileName="src/App.csx" codeFormat="commonjs"
+const { FC } = require("react");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+const { useI18nHTMLAttributes } = require("./hooks/useI18nHTMLAttributes");
+require("./App.css");
+
+const AppContent = () => {
+  // تطبيق الخطاف لتحديث سمات lang و dir لعلامة <html> بناءً على اللغة.
+  useI18nHTMLAttributes();
+
+  // ... بقية المكون الخاص بك
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+module.exports = App;
+```
+
+من خلال تطبيق هذه التغييرات، سيقوم تطبيقك بـ:
+
+- ضمان أن تعكس سمة **اللغة** (`lang`) اللغة الحالية بشكل صحيح، وهو أمر مهم لتحسين محركات البحث وسلوك المتصفح.
+- ضبط **اتجاه النص** (`dir`) وفقًا للغة، مما يعزز قابلية القراءة وسهولة الاستخدام للغات ذات اتجاهات قراءة مختلفة.
+- توفير تجربة أكثر **وصولًا**، حيث تعتمد تقنيات المساعدة على هذه السمات لتعمل بشكل مثالي.
+
+### إعداد TypeScript
+
+يستخدم Intlayer توسيع الوحدة للاستفادة من TypeScript وجعل قاعدة الكود الخاصة بك أقوى.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+
+تأكد من أن إعدادات TypeScript الخاصة بك تتضمن الأنواع التي يتم إنشاؤها تلقائيًا.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... إعدادات TypeScript الحالية الخاصة بك
+  "include": [
+    // ... إعدادات TypeScript الحالية الخاصة بك
+    ".intlayer/**/*.ts", // تضمين الأنواع التي يتم إنشاؤها تلقائيًا
+  ],
+}
+```
+
+### إعداد Git
+
+يوصى بتجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer. يتيح لك ذلك تجنب إضافتها إلى مستودع Git الخاص بك.
+
+للقيام بذلك، يمكنك إضافة التعليمات التالية إلى ملف `.gitignore` الخاص بك:
+
+```plaintext fileName=".gitignore"
+# تجاهل الملفات التي يتم إنشاؤها بواسطة Intlayer
+.intlayer
+```
+
+### التعمق أكثر
+
+للتعمق أكثر، يمكنك تنفيذ [المحرر المرئي](https://github.com/aymericzip/intlayer/blob/main/docs/ar/intlayer_visual_editor.md) أو نقل المحتوى الخاص بك باستخدام [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/ar/intlayer_CMS.md).