@intlayer/docs 5.5.8

package/ar/packages/next-intlayer/index.md

@@ -0,0 +1,267 @@
+# next-intlayer: حزمة NPM لتدويل (i18n) تطبيق Next.js
+
+**Intlayer** هي مجموعة من الحزم المصممة خصيصًا لمطوري JavaScript. وهي متوافقة مع أطر العمل مثل React وNext.js وExpress.js.
+
+**حزمة `next-intlayer`** تتيح لك تدويل تطبيق Next.js الخاص بك. توفر موفري السياق وخطافات لتدويل Next.js. بالإضافة إلى ذلك، تتضمن مكون إضافي لـ Next.js لدمج Intlayer مع [Webpack](https://webpack.js.org/) أو [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack)، بالإضافة إلى وسيط لاكتشاف اللغة المفضلة للمستخدم، وإدارة ملفات تعريف الارتباط، ومعالجة إعادة توجيه الروابط.
+
+## لماذا تدويل تطبيق Next.js الخاص بك؟
+
+تدويل تطبيق Next.js الخاص بك أمر ضروري لخدمة جمهور عالمي بفعالية. يتيح لتطبيقك تقديم المحتوى والرسائل بلغة المستخدم المفضلة. هذه القدرة تعزز تجربة المستخدم وتوسع نطاق تطبيقك بجعله أكثر وصولًا وملاءمة للأشخاص من خلفيات لغوية مختلفة.
+
+## لماذا دمج Intlayer؟
+
+- **إدارة محتوى مدعومة بـ JavaScript**: استغل مرونة JavaScript لتعريف وإدارة المحتوى بكفاءة.
+- **بيئة آمنة من الأخطاء**: استفد من TypeScript لضمان أن تكون جميع تعريفات المحتوى دقيقة وخالية من الأخطاء.
+- **ملفات محتوى متكاملة**: احتفظ بترجماتك قريبة من مكوناتها ذات الصلة، مما يعزز القابلية للصيانة والوضوح.
+
+## التثبيت
+
+قم بتثبيت الحزمة اللازمة باستخدام مدير الحزم المفضل لديك:
+
+```bash packageManager="npm"
+npm install next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add next-intlayer
+```
+
+## مثال على الاستخدام
+
+مع Intlayer، يمكنك إعلان المحتوى الخاص بك بطريقة منظمة في أي مكان في قاعدة الكود الخاصة بك.
+
+بشكل افتراضي، يقوم Intlayer بفحص الملفات ذات الامتداد `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> يمكنك تعديل الامتداد الافتراضي عن طريق تعيين خاصية `contentDir` في [ملف التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/ar/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── ServerComponent
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── ServerComponent
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── ServerComponent
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### إعلان المحتوى الخاص بك
+
+`next-intlayer` مصمم للعمل مع [حزمة `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/intlayer/index.md). `intlayer` هي حزمة تتيح لك إعلان المحتوى الخاص بك في أي مكان في الكود الخاص بك. تقوم بتحويل إعلانات المحتوى متعدد اللغات إلى قواميس منظمة تندمج بسلاسة في تطبيقك.
+
+إليك مثال على إعلان المحتوى:
+
+```tsx fileName="src/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ar: "مرحبًا بالعالم",
+    }),
+    numberOfCar: enu({
+      "<-1": "أقل من ناقص سيارة واحدة",
+      "-1": "ناقص سيارة واحدة",
+      "0": "لا سيارات",
+      "1": "سيارة واحدة",
+      ">5": "بعض السيارات",
+      ">19": "الكثير من السيارات",
+    }),
+  },
+} satisfies Dictionary;
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ar: "مرحبًا بالعالم",
+    }),
+    numberOfCar: enu({
+      "<-1": "أقل من ناقص سيارة واحدة",
+      "-1": "ناقص سيارة واحدة",
+      "0": "لا سيارات",
+      "1": "سيارة واحدة",
+      ">5": "بعض السيارات",
+      ">19": "الكثير من السيارات",
+    }),
+  },
+};
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ar: "مرحبًا بالعالم",
+    }),
+    numberOfCar: enu({
+      "<-1": "أقل من ناقص سيارة واحدة",
+      "-1": "ناقص سيارة واحدة",
+      "0": "لا سيارات",
+      "1": "سيارة واحدة",
+      ">5": "بعض السيارات",
+      ">19": "الكثير من السيارات",
+    }),
+  },
+};
+
+module.exports = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo",
+        "ar": "مرحبًا بالعالم"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "أقل من ناقص سيارة واحدة",
+        "-1": "ناقص سيارة واحدة",
+        "0": "لا سيارات",
+        "1": "سيارة واحدة",
+        ">5": "بعض السيارات",
+        ">19": "الكثير من السيارات"
+      }
+    }
+  }
+}
+```
+
+### استخدام المحتوى في الكود الخاص بك
+
+بمجرد إعلان المحتوى الخاص بك، يمكنك استخدامه في الكود الخاص بك. إليك مثال على كيفية استخدام المحتوى في مكون React:
+
+```tsx {4,7} fileName="src/components/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // إنشاء إعلان محتوى ذي صلة
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // إنشاء إعلان محتوى ذي صلة
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // إنشاء إعلان محتوى ذي صلة
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## إتقان تدويل تطبيق Next.js الخاص بك
+
+يوفر Intlayer العديد من الميزات لمساعدتك في تدويل تطبيق Next.js الخاص بك. إليك بعض الميزات الرئيسية:
+
+- **تدويل مكونات الخادم**: يتيح لك Intlayer تدويل مكونات الخادم بنفس طريقة مكونات العميل. هذا يعني أنه يمكنك استخدام نفس إعلانات المحتوى لكل من مكونات العميل والخادم.
+- **وسيط لاكتشاف اللغة**: يوفر Intlayer وسيطًا لاكتشاف اللغة المفضلة للمستخدم. يُستخدم هذا الوسيط لاكتشاف اللغة المفضلة للمستخدم وإعادة توجيههم إلى الرابط المناسب كما هو محدد في [التكوين](https://github.com/aymericzip/intlayer/blob/main/docs/ar/configuration.md).
+- **تدويل البيانات الوصفية**: يوفر Intlayer طريقة لتدويل البيانات الوصفية الخاصة بك، مثل عنوان صفحتك، باستخدام وظيفة `generateMetadata` التي يوفرها Next.js. يمكنك استخدام وظيفة `getTranslation` لترجمة البيانات الوصفية الخاصة بك.
+- **تدويل sitemap.xml وrobots.txt**: يتيح لك Intlayer تدويل ملفات sitemap.xml وrobots.txt الخاصة بك. يمكنك استخدام وظيفة `getMultilingualUrls` لإنشاء روابط متعددة اللغات لملف sitemap الخاص بك.
+- **تدويل الروابط**: يتيح لك Intlayer تدويل الروابط الخاصة بك باستخدام وظيفة `getMultilingualUrls`. تقوم هذه الوظيفة بإنشاء روابط متعددة اللغات لملف sitemap الخاص بك.
+
+**لتعلم المزيد عن هذه الميزات، راجع دليل [تدويل Next.js (i18n) مع Intlayer وNext.js 15 App Router](https://github.com/aymericzip/intlayer/blob/main/docs/ar/intlayer_with_nextjs_15.md).**
+
+## الوظائف التي توفرها حزمة `next-intlayer`
+
+توفر حزمة `next-intlayer` أيضًا بعض الوظائف لمساعدتك في تدويل تطبيقك.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/next-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/next-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/next-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/next-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/ar/packages/next-intlayer/useIntlayerAsync.md)

package/ar/packages/next-intlayer/t.md

@@ -0,0 +1,341 @@
+# التوثيق: وظيفة `t` في `next-intlayer`
+
+وظيفة `t` في حزمة `next-intlayer` هي أداة أساسية للتدويل المضمّن داخل تطبيق Next.js الخاص بك. تتيح لك تعريف الترجمات مباشرة داخل مكوناتك، مما يجعل من السهل عرض المحتوى المحلي بناءً على اللغة الحالية.
+
+---
+
+## نظرة عامة
+
+تُستخدم وظيفة `t` لتوفير الترجمات للغات المختلفة مباشرة في مكوناتك. من خلال تمرير كائن يحتوي على الترجمات لكل لغة مدعومة، تُرجع `t` الترجمة المناسبة بناءً على سياق اللغة الحالي في تطبيق Next.js الخاص بك.
+
+---
+
+## الميزات الرئيسية
+
+- **ترجمات مضمّنة**: مثالية للنصوص السريعة والمضمّنة التي لا تتطلب إعلان محتوى منفصل.
+- **اختيار اللغة تلقائيًا**: تُرجع الترجمة المطابقة للغة الحالية تلقائيًا.
+- **دعم TypeScript**: يوفر أمان الأنواع والإكمال التلقائي عند استخدامه مع TypeScript.
+- **تكامل سهل**: يعمل بسلاسة داخل المكونات العميلة والخادم في Next.js.
+
+---
+
+## توقيع الوظيفة
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### المعلمات
+
+- `translations`: كائن حيث تكون المفاتيح هي رموز اللغات (مثل `en`, `fr`, `es`) والقيم هي النصوص المترجمة المقابلة.
+
+### الإرجاع
+
+- سلسلة تمثل المحتوى المترجم للغة الحالية.
+
+---
+
+## أمثلة الاستخدام
+
+### استخدام `t` في مكون عميل
+
+تأكد من تضمين التوجيه `'use client';` في أعلى ملف المكون الخاص بك عند استخدام `t` في مكون على جانب العميل.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+      ar: "هذا هو محتوى مثال لمكون عميل",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+      ar: "هذا هو محتوى مثال لمكون عميل",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es le contenido d un ejemplo de componente cliente",
+      ar: "هذا هو محتوى مثال لمكون عميل",
+    })}
+  </p>
+);
+```
+
+### استخدام `t` في مكون خادم
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      ar: "هذا هو محتوى مثال لمكون خادم",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      ar: "هذا هو محتوى مثال لمكون خادم",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      ar: "هذا هو محتوى مثال لمكون خادم",
+    })}
+  </p>
+);
+```
+
+### الترجمات المضمّنة في السمات
+
+تعتبر وظيفة `t` مفيدة بشكل خاص للترجمات المضمّنة في سمات JSX.
+عند توطين السمات مثل `alt`, `title`, `href`, أو `aria-label`، يمكنك استخدام `t` مباشرة داخل السمة.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    ar: "إرسال",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    ar: "إرسال",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+      ar: "منظر جميل",
+    })}
+  />
+</button>
+```
+
+---
+
+## مواضيع متقدمة
+
+### تكامل TypeScript
+
+وظيفة `t` آمنة من حيث الأنواع عند استخدامها مع TypeScript، مما يضمن توفير جميع اللغات المطلوبة.
+
+```typescript codeFormat="typescript"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ar: "مرحبًا",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ar: "مرحبًا",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ar: "مرحبًا",
+};
+
+const greeting = t(translations);
+```
+
+### اكتشاف اللغة والسياق
+
+في `next-intlayer`، تتم إدارة اللغة الحالية من خلال موفري السياق: `IntlayerClientProvider` و `IntlayerServerProvider`. تأكد من أن هؤلاء الموفّرين يلفون مكوناتك وأن الخاصية `locale` يتم تمريرها بشكل صحيح.
+
+#### مثال:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* مكوناتك هنا */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* مكوناتك هنا */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* مكوناتك هنا */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## الأخطاء الشائعة واستكشاف الأخطاء وإصلاحها
+
+### `t` تُرجع undefined أو ترجمة غير صحيحة
+
+- **السبب**: لم يتم تعيين اللغة الحالية بشكل صحيح، أو الترجمة للغة الحالية مفقودة.
+- **الحل**:
+  - تحقق من أن `IntlayerClientProvider` أو `IntlayerServerProvider` تم إعدادهما بشكل صحيح مع اللغة المناسبة.
+  - تأكد من أن كائن الترجمات الخاص بك يتضمن جميع اللغات الضرورية.
+
+### الترجمات المفقودة في TypeScript
+
+- **السبب**: كائن الترجمات لا يفي باللغات المطلوبة، مما يؤدي إلى أخطاء في TypeScript.
+- **الحل**: استخدم نوع `IConfigLocales` لفرض اكتمال الترجمات.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // فقدان 'es' سيتسبب في خطأ TypeScript [!code error]
+  ar: "نص",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // فقدان 'es' سيتسبب في خطأ TypeScript [!code error]
+  ar: "نص",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // فقدان 'es' سيتسبب في خطأ TypeScript [!code error]
+  ar: "نص",
+};
+
+const text = t(translations);
+```
+
+---
+
+## نصائح للاستخدام الفعّال
+
+1. **استخدم `t` للترجمات المضمّنة البسيطة**: مثالية لترجمة النصوص الصغيرة مباشرة داخل مكوناتك.
+2. **فضل `useIntlayer` للمحتوى المنظم**: للحصول على ترجمات أكثر تعقيدًا وإعادة استخدام المحتوى، قم بتعريف المحتوى في ملفات الإعلان واستخدم `useIntlayer`.
+3. **توفير اللغة بشكل متسق**: تأكد من أن اللغة يتم توفيرها بشكل متسق عبر تطبيقك من خلال الموفّرين المناسبين.
+4. **استفد من TypeScript**: استخدم أنواع TypeScript لاكتشاف الترجمات المفقودة وضمان أمان الأنواع.
+
+---
+
+## الخاتمة
+
+وظيفة `t` في `next-intlayer` هي أداة قوية ومريحة لإدارة الترجمات المضمّنة في تطبيقات Next.js الخاصة بك. من خلال دمجها بشكل فعّال، تعزز قدرات التدويل لتطبيقك، مما يوفر تجربة أفضل للمستخدمين في جميع أنحاء العالم.
+
+للحصول على استخدام أكثر تفصيلاً وميزات متقدمة، راجع [توثيق next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/ar/intlayer_visual_editor.md).
+
+---
+
+**ملاحظة**: تذكر إعداد `IntlayerClientProvider` و `IntlayerServerProvider` بشكل صحيح لضمان تمرير اللغة الحالية بشكل صحيح إلى مكوناتك. هذا أمر بالغ الأهمية لكي تُرجع وظيفة `t` الترجمات الصحيحة.