@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/ar/build_dictionaries.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: كيفية بناء القواميس؟
+description: تعلم كيفية بناء القواميس.
+keywords:
+  - بناء
+  - قواميس
+  - intlayer
+  - أمر
+  - مراقبة
+  - vscode
+  - إضافة
+  - إطار عمل
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - build-dictionaries
+---
+
+# بناء القواميس
+
+## كيفية بناء القواميس
+
+يوفر Intlayer أداة سطر أوامر لبناء القواميس.
+
+```bash
+npx intlayer dictionaries build
+```
+
+يقوم هذا الأمر بـ:
+
+- مسح جميع ملفات إعلان المحتوى (`.content.{ts,tsx,js,mjs,cjs,json,...}`) في مشروعك.
+- إنشاء القواميس وتخزينها في مجلد `.intlayer/dictionary`.
+
+### وضع المراقبة
+
+إذا كنت ترغب في تحديث القواميس تلقائيًا عند إجراء تغييرات على ملفات إعلان المحتوى، فقم بتشغيل الأمر التالي:
+
+```bash
+npx intlayer dictionaries build --watch
+```
+
+في هذا الوضع، سيقوم Intlayer بمسح وبناء القواميس كلما تم إجراء تغييرات على ملفات إعلان المحتوى وتحديث مجلد `.intlayer/dictionary` تلقائيًا.
+
+### استخدام إضافة VSCode
+
+يمكنك أيضًا استخدام [إضافة Intlayer لـ VSCode](https://github.com/aymericzip/intlayer/tree/main/docs/ar/vs_code_extension.md) لتعزيز تجربتك مع Intlayer في VSCode.
+
+### استخدام الإضافة لإطار عمل التطبيق المفضل لديك
+
+إذا كنت تستخدم إطار عمل مثل Next.js (Webpack / Turbopack)، Vite، أو React Native، Lynx، إلخ، فإن Intlayer يوفر إضافة يمكنك استخدامها لدمج Intlayer في تطبيقك.
+
+سيقوم Intlayer ببناء القواميس قبل بناء تطبيقك.
+وبنفس الطريقة، في وضع التطوير، سيراقب Intlayer التغييرات في ملفات إعلان المحتوى ويعيد بناء القواميس تلقائيًا.
+
+لذا، ارجع إلى الوثائق الخاصة بإطار عملك لتتعلم كيفية دمج الإضافة.

package/frequent_questions/ar/build_error_CI_CD.md

@@ -0,0 +1,75 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: خطأ في البناء في CI/CD
+description: تعلّم كيفية إصلاح أخطاء البناء التي تحدث في بيئات CI/CD.
+keywords:
+  - بناء
+  - خطأ
+  - ci
+  - cd
+  - خط الأنابيب
+  - intlayer
+  - القواميس
+  - next.js
+  - ما قبل البناء
+  - الأتمتة
+slugs:
+  - doc
+  - faq
+  - build-error-ci-cd
+---
+
+# خطأ في البناء في CI/CD
+
+إذا حصلت على خطأ مثل هذا في Next.js:
+
+```text
+Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error
+```
+
+إليك بعض الحلول:
+
+## 1. القواميس المفقودة
+
+تأكد من أن القواميس تم بناؤها في مرحلة البناء.
+
+من الشائع أن يعمل البناء محليًا ولكن لا يعمل على CI/CD. السبب هو أنه محليًا، يكون مجلد `.intlayer` موجودًا، ولكن على CI/CD، لا يكون موجودًا لأنه مستبعد من البناء.
+
+يمكنك إصلاح ذلك عن طريق إضافة سكربت ما قبل البناء في ملف `package.json` الخاص بمشروعك.
+
+```json5 fileName=package.json
+{
+  // ...
+  "scripts": {
+    "prebuild": "npx intlayer dictionaries build", // سيتم تشغيله قبل البناء
+    "build": "next build",
+  },
+}
+```
+
+> لاحظ أنه إذا كنت تستخدم دالة `withIntlayer`، أو الإضافة المكافئة للباندلر في إطار عملك، فسيتم تشغيل سكربت ما قبل البناء قبل البناء.
+
+## 2. المتغيرات البيئية المفقودة أثناء وقت البناء / التشغيل
+
+في الحاويات، أو المنصات التي تعتمد النشر التلقائي، يُنصح باستبعاد ملف `.env` من البناء.
+
+```text fileName=".gitignore or .dockerignore"
+# المتغيرات البيئية
+.env
+**/.env
+.env.*
+**/.env.*
+```
+
+إذا لم تكن المتغيرات البيئية متاحة أثناء وقت البناء، فسيتم إصدار خطأ.
+
+```ts
+import { Metadata } from "next";
+
+export const generateMetadata = async ({ params }): Promise<Metadata> => ({
+  metadataBase: new URL(process.env.NEXT_PUBLIC_URL),
+});
+```
+
+من المحتمل أن هذا لا يتعلق بـ Intlayer. لذا تحقق من المتغيرات البيئية الخاصة بك أثناء وقت البناء على منصة CI/CD الخاصة بك.

package/frequent_questions/ar/customized_locale_list.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: كيفية تخصيص قائمة اللغات؟
+description: تعلّم كيفية تخصيص قائمة اللغات.
+keywords:
+  - اللغات
+  - القائمة
+  - intlayer
+  - التهيئة
+  - availableLocales
+  - defaultLocale
+  - useLocale
+  - hook
+  - اللغة
+  - القائمة
+slugs:
+  - doc
+  - faq
+  - customized-locale-list
+---
+
+# هل من الممكن حظر نوع لغة، مثل الإنجليزية؟ أنا أضيف الإنجليزية في قواميسي لكن لا أريد أن تكون الإنجليزية متاحة على الموقع بعد
+
+نعم، يمكنك حظر نوع لغة، مثل الإنجليزية، باستخدام خيار `availableLocales` في تهيئة Intlayer.
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  locales: [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH],
+  availableLocales: [Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+أو
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const locales = [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH];
+
+const config: IntlayerConfig = {
+  locales,
+  availableLocales: locales.filter((locale) => locale !== Locales.ENGLISH),
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+سيؤدي هذا التهيئة إلى تغيير أنواع دالة `t()` الخاصة بك لتشمل فقط اللغات المتاحة.
+
+اللغات المتاحة خيار اختياري، إذا لم تقم بتوفيرها، فستكون جميع اللغات متاحة.
+
+كن حذرًا، يجب أن تكون جميع اللغات المدرجة في خيار `availableLocales` مدرجة أيضًا في خيار `locales`.
+
+لاحظ أنه إذا كنت تستخدم الخطاف `useLocale`، فسيتم استخدام خيار `availableLocales` لتحديد الوصول إلى قائمة اللغات.
+
+```ts
+import { useLocale } from "intlayer";
+
+const { availableLocales } = useLocale();
+
+console.log(availableLocales); // [Locales.FRENCH, Locales.SPANISH]
+```

package/frequent_questions/ar/domain_routing.md

@@ -0,0 +1,115 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: كيفية تكوين التوجيه بناءً على النطاق؟
+description: تعلّم كيفية تكوين التوجيه بناءً على النطاق.
+keywords:
+  - النطاق
+  - التوجيه
+  - intlayer
+  - التكوين
+  - الوسيط
+  - react-router
+  - vue-router
+  - next.js
+  - vite
+  - الإطار
+slugs:
+  - doc
+  - faq
+  - domain-routing
+---
+
+# كيف أقوم بتكوين **التوجيه بناءً على النطاق** مع Intlayer بدلاً من مسارات `/[locale]/`؟
+
+## إجابة مختصرة
+
+التوجيه بناءً على النطاق أبسط من التوجيه بناءً على المسار (`example.com/[locale]/`) لأنه يمكنك تخطي كل تكوين الوسيط والتوجيه. فقط قم بنشر تطبيقك على كل نطاق لغة واضبط متغير بيئة واحد لكل نطاق.
+
+## خطوة بخطوة
+
+1. **انشر مرة واحدة لكل نطاق** (`example.com`، `exemple.fr`، `ejemplo.es`، …).
+2. لكل نشر، قم بتعيين `LOCALE` (ومتغيرات بيئة Intlayer المعتادة) إلى اللغة التي يجب أن يخدمها النطاق.
+3. أشر إلى هذا المتغير كـ `defaultLocale` في ملف `intlayer.config.[ts|js]` الخاص بك.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 النطاق يحدد اللغة
+  },
+  // ... بقية التكوين الخاص بك
+};
+
+export default config;
+```
+
+هذا كل شيء — يعمل بنفس الطريقة مع **Next.js**، **Vite + React**، **Vite + Vue**، إلخ.
+
+## ماذا لو كان كل النطاقات تشير إلى نفس النشر؟
+
+إذا كانت جميع النطاقات تشير إلى نفس حزمة التطبيق، فستحتاج إلى اكتشاف المضيف أثناء وقت التشغيل وتمرير اللغة يدويًا عبر المزود.
+
+### لـ Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname();
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### لـ Vue
+
+```ts
+ts;
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+استبدل `getLocaleFromHostname()` بمنطق البحث الخاص بك.
+
+## تحديث مبدل اللغة الخاص بك
+
+عند استخدام التوجيه المعتمد على النطاق، يعني تغيير اللغة التنقل إلى نطاق آخر:
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## فوائد التوجيه المعتمد على النطاق
+
+1. **تكوين أبسط**: لا حاجة لتكوين `intlayerMiddleware`، `generateStaticParams`، `react-router`، أو `vue-router`
+2. **تحسين محركات البحث (SEO)**: لكل لغة نطاق خاص بها
+3. **عناوين URL أنظف**: لا يوجد بادئة للغة في المسار
+4. **صيانة أسهل**: كل نشر للغة مستقل

package/frequent_questions/ar/esbuild_error.md

@@ -0,0 +1,30 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: خطأ ESBuild
+description: تعلم كيفية إصلاح أخطاء ESBuild.
+keywords:
+  - esbuild
+  - خطأ
+  - intlayer
+  - إضافة
+  - إطار عمل
+  - next.js
+  - vite
+  - react-native
+  - lynx
+slugs:
+  - doc
+  - faq
+  - esbuild-error
+---
+
+# خطأ ESBuild
+
+إذا واجهت خطأ ESBuild أثناء عملية البناء، فمن المحتمل أن إضافة Intlayer لم تُضبط بشكل صحيح.
+
+تتحمل ESBuild مسؤولية قراءة ملفات إعلان المحتوى (`.content.{ts,js,mjs,cjs,json}`) وإنشاء القواميس المقابلة في مجلد `.intlayer/dictionary`. بالإضافة إلى قراءة ملف التكوين (`intlayer.config.ts`).
+
+توفر Intlayer إضافات للتكامل مع أدوات التجميع الخاصة بك. تم تصميمها لإنشاء أسماء مستعارة للمكونات التي من المفترض أن تعمل على جانب الخادم فقط.
+
+إذا كنت تستخدم إطار عمل مثل Next.js (Webpack / Turbopack)، Vite، أو React Native، Lynx، إلخ. توفر Intlayer إضافة يمكنك استخدامها لدمج Intlayer في تطبيقك. لذا ارجع إلى الوثائق الخاصة بإطار العمل الذي تستخدمه لتتعلم كيفية دمج الإضافة.

package/frequent_questions/ar/get_locale_cookie.md

@@ -0,0 +1,143 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: كيفية استرجاع اللغة من الكوكيز / الرؤوس؟
+description: تعلّم كيفية استرجاع اللغة من الكوكيز / الرؤوس.
+keywords:
+  - الكوكيز
+  - الرؤوس
+  - intlayer
+  - اللغة
+  - هوك
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# كيفية استرجاع اللغة من الكوكيز / الرؤوس
+
+## استخدام الهوكس (مُوصى به)
+
+في معظم حالات الاستخدام، يُنصح باسترجاع اللغة الحالية باستخدام هوك `useLocale` لأنه يتم حله تلقائيًا. هذا يعمل بطريقة مشابهة للـ `useLocale` القابل للاستخدام في Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// أو import { useLocale } من "react-intlayer";
+// أو import { useLocale } من "vue-intlayer";
+
+// استخدام جانب العميل
+const { locale } = useLocale();
+```
+
+بالنسبة لمكونات الخادم، يمكنك استيراده من:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+هناك أيضًا هوك `useLocaleCookie` الذي يحل فقط قيمة الكوكيز.
+
+## تكوين الكوكيز يدويًا
+
+يمكنك إعلان اسم كوكيز مخصص كما يلي
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // الافتراضي هو 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+استرجاعها كما يلي
+
+### جانب العميل
+
+```ts
+// استخدام اسم الكوكيز الافتراضي
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// استخدام اسم كوكيز مخصص
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### جانب الخادم (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// استخدام اسم الكوكيز الافتراضي
+const locale = cookies().get("intlayer-locale")?.value;
+
+// استخدام اسم كوكيز مخصص
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### إذا لم يتم تعيين اللغة بعد
+
+يتم تعيين اللغة ككوكيز فقط بمجرد أن يختار المستخدم اللغة صراحةً. بشكل افتراضي، للزوار الجدد، يتم تفسير اللغة من حقول الرؤوس.
+
+يمكنك اكتشاف اللغة المفضلة للمستخدم من رؤوس الطلب. فيما يلي مثال على كيفية التعامل مع ذلك:
+
+```ts
+/**
+ * يكتشف اللغة من رؤوس الطلب
+ *
+ * رأس accept-language هو الأهم لاكتشاف اللغة.
+ * يحتوي على قائمة من رموز اللغات مع قيم الجودة (q-values) التي تشير
+ * إلى اللغات المفضلة للمستخدم بترتيب التفضيل.
+ *
+ * مثال: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US هي اللغة الأساسية (q=1.0 مفترضة)
+ * - en هو الخيار الثاني (q=0.9)
+ * - fr هو الخيار الثالث (q=0.8)
+ * - es هو الخيار الرابع (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * مثال على رؤوس المفاوضة التي ترسلها المتصفحات عادةً
+ * تساعد هذه الرؤوس في تحديد اللغة المفضلة للمستخدم
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// مثال على الاستخدام:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/ar/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: أمر Intlayer غير معرف
+description: تعلّم كيفية إصلاح خطأ أمر intlayer غير معرف.
+keywords:
+  - intlayer
+  - أمر
+  - غير معرف
+  - خطأ
+  - vscode
+  - امتداد
+  - مكون إضافي
+  - إطار عمل
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - intlayer-command-undefined
+---
+
+# أمر Intlayer غير معرف
+
+## نظرة عامة
+
+يوفر CLI الخاص بـ Intlayer طريقة مريحة للتحكم في محتوى intlayer الخاص بك، بما في ذلك بناء القواميس، ودفع الترجمات، والمزيد. ومع ذلك، فهو ليس ضروريًا لعمل مشروعك. إذا كنت تستخدم مكون التجميع الإضافي (مثل `withIntlayer()` لـ Next.js أو `intlayerPlugin()` لـ Vite)، فسيقوم Intlayer تلقائيًا ببناء القواميس أثناء بناء التطبيق أو بدء تشغيل خادم التطوير. في وضع التطوير، سيقوم أيضًا بمراقبة التغييرات وإعادة بناء ملفات إعلان المحتوى تلقائيًا.
+
+يمكنك الوصول إلى أوامر intlayer بطرق مختلفة:
+
+- استخدام أمر CLI `intlayer` مباشرة
+- استخدام [امتداد VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/vs_code_extension.md)
+- استخدام SDK الخاص بـ `@intlayer/cli`
+
+## المشكلة
+
+عند محاولة استخدام أمر `intlayer`، قد تواجه هذا الخطأ:
+
+```bash
+'intlayer' غير معروف كأمر داخلي أو خارجي،
+برنامج قابل للتشغيل أو ملف دفعي.
+```
+
+## الحلول
+
+جرّب هذه الحلول بالترتيب:
+
+1. **تحقق من تثبيت الأمر**
+
+```bash
+npx intlayer -h
+```
+
+الناتج المتوقع:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            output the version number
+    -h, --help               display help for command
+
+Commands:
+    dictionary|dictionaries  Dictionaries operations
+    configuration|config     Configuration operations
+    help [command]           display help for command
+```
+
+2. **تثبيت حزمة intlayer-cli بشكل عام**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> لا يجب أن يكون ذلك ضروريًا إذا كنت قد قمت بالفعل بتثبيت حزمة `intlayer`
+
+3. **تثبيت الحزمة بشكل عام**
+
+```bash
+npm install intlayer -g
+```
+
+4. **أعد تشغيل الطرفية**
+   أحيانًا يكون من الضروري إعادة تشغيل الطرفية للتعرف على الأوامر الجديدة.
+
+5. **تنظيف وإعادة التثبيت**
+   إذا لم تنجح الحلول السابقة:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **التحقق من ملفات التثبيت**
+   إذا استمرت المشكلة، تحقق من وجود هذه الملفات:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (يجب أن يحتوي على حقل `bin` يشير إلى `./dist/cjs/cli.cjs`)
+
+7. **التحقق من متغير بيئة PATH**
+   تأكد من أن دليل npm العام موجود في PATH الخاص بك:
+
+```bash
+# لأنظمة يونكس (macOS/Linux)
+echo $PATH
+# يجب أن يتضمن شيئًا مثل /usr/local/bin أو ~/.npm-global/bin
+
+# لنظام ويندوز
+echo %PATH%
+# يجب أن يتضمن دليل npm العام
+```
+
+8. **استخدام npx مع المسار الكامل**
+   إذا لم يتم العثور على الأمر بعد، جرب استخدام npx مع المسار الكامل:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **التحقق من وجود تثبيتات متضاربة**
+
+```bash
+# عرض جميع الحزم المثبتة عالميًا
+npm list -g --depth=0
+
+# إزالة أي تثبيتات متضاربة عالمياً
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# ثم إعادة التثبيت
+npm install -g intlayer
+```
+
+10. **التحقق من إصدارات Node.js و npm**
+    تأكد من أنك تستخدم إصدارات متوافقة:
+
+```bash
+node --version
+npm --version
+```
+
+    إذا كنت تستخدم إصدارًا قديمًا، فكر في تحديث Node.js و npm.
+
+11. **التحقق من مشاكل الأذونات**
+    إذا كنت تواجه أخطاء في الأذونات:
+
+    ```bash
+    # لأنظمة يونكس
+    sudo npm install -g intlayer
+
+    # أو تغيير الدليل الافتراضي لـ npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # أضف إلى ملف ~/.profile أو ~/.bashrc الخاص بك:
+    export PATH=~/.npm-global/bin:$PATH
+    ```