@intlayer/docs 9.4.2 → 9.4.3

package/blog/ar/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "تنسيق التواريخ والأرقام حسب اللغة باستخدام Intl"
+description: أنت غالباً لا تحتاج إلى مكتبة تنسيق خارجية. كيف يتعامل Intl مع التواريخ والأرقام والعملات والقوائم حسب اللغة، وتكلفة التخزين المؤقت، وخطأ المنطقة الزمنية في الإنتاج.
+keywords:
+  - تنسيق التاريخ حسب اللغة
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - تنسيق العملة حسب اللغة
+  - تنسيق الوقت النسبي
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# تنسيق التواريخ والأرقام حسب اللغة باستخدام Intl
+
+ترجمة النصوص هي النصف المرئي فقط من التدويل (i18n). أما النصف الآخر الذي يولد تقارير الأخطاء باستمرار فهو التنسيق: مستخدم ألماني يرى `1,234.56` بدلاً من `1.234,56`، أو مستخدم ياباني يرى `08/02/2026` ويفهم أنه شهر أغسطس، أو تاريخ يتم عرضه بشكل مختلف بين الخادم والمتصفح فيؤدي إلى تعطل الصفحة بسبب عدم تطابق الهيدرة (Hydration mismatch) في React.
+
+لا شيء من هذا يتطلب تثبيت مكتبة خارجية. واجهة `Intl` البرمجية القياسية مدمجة بالفعل في كل بيئة تشغيل حديثة.
+
+## جدول المحتويات
+
+<TOC/>
+
+## ابدأ بحذف دوال مساعدة التواريخ المكتوبة يدوياً
+
+تحتوي معظم المشاريع تقريباً على دالة `formatDate` كُتبت قبل أن يفكر أي شخص في دعم اللغات المتعددة. وهي تثبت ترتيباً فجائياً، وفاصلاً محدداً، وغالباً أسماء أشهر باللغة الإنجليزية.
+
+```ts
+// الكود الذي يجب عليك حذفه:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+تحل `Intl.DateTimeFormat` محلها بالكامل وتضمن صحة التنسيق في كل لغة:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+ينطبق الأمر ذاته على الأرقام. استدعاء `toFixed(2)` ينتج `1234.56` في كل مكان، وهو أمر خاطئ في معظم الدول الأوروبية.
+
+## ما تغطيه واجهة `Intl`
+
+| الواجهة البرمجية          | استخداماتها                                                        |
+| :------------------------ | :----------------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | التواريخ والأوقات مع إعدادات جاهزة مثل `dateStyle` و `timeStyle`   |
+| `Intl.NumberFormat`       | الأرقام العشرية، العملات، النسب المئوية، الوحدات، والترميز المختصر |
+| `Intl.RelativeTimeFormat` | "منذ 3 أيام"، "خلال ساعتين"                                        |
+| `Intl.ListFormat`         | دمج القوائم مثل "أ، ب، وج"                                         |
+| `Intl.PluralRules`        | تحديد فئة الجمع المناسبة للرقم                                     |
+| `Intl.Collator`           | الترتيب الهجائي السليم للنصوص وفق قواعد اللغة                      |
+
+تعتبر `Intl.Collator` من أكثر الأدوات التي يغفل عنها المطورون. ترتيب النصوص عبر `array.sort()` العادية يعتمد على ترتيب محارف يونيكود، مما يضع الحروف المشكولة بعد حرف `z` ويخل بترتيب الحروف الخاصة. عند ترتيب قوائم يراها المستخدم، استخدم دائماً أداة collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("ar").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## تفضيل الإعدادات الجاهزة على الخيارات المصنوعة يدوياً
+
+تتيح خيارات `dateStyle` و `timeStyle` للغة نفسها تحديد الترتيب المنطقي والفواصل المناسبة. بينما يمنحك تحديد `year` و `month` و `day` يدوياً تحكماً نادراً ما يكون مرغوباً، لأن الترتيب الصحيح يختلف باختلاف الثقافات، وتنقض بذلك بيانات CLDR بافتراضات غير دقيقة.
+
+```ts
+// اللغة تحدد التنسيق المناسب تلقائياً:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// تحديد التنسيق يدوياً يجعله غير مناسب في مناطق أخرى:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+لا تلجأ لتحديد المكونات بشكل صريح إلا إذا كانت هناك متطلبات تصميمية تلزمك بعرض ثابت ومحدد، كأعمدة الجداول الضيقة.
+
+## إنشاء كائنات التنسيق عملية مكلفة برمجياً
+
+هذه هي نقطة الأداء الجوهرية. يتطلب بناء كائن `Intl.NumberFormat` تحميل بيانات لغوية ضخمة، وهي عملية تفوق بمراحل استدعاء `.format()` اللاحق. وتكرار إنشائها داخل حلقة تكرار على ألف عنصر يسبب بطئاً ملحوظاً.
+
+```ts
+// إعادة إنشاء المنسق في كل دورة (غير فعال):
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// إنشاؤه مرة واحدة ثم إعادة استخدامه (فعال):
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+تنطوي دوال `toLocaleDateString()` و `toLocaleString()` على نفس المشكلة الخفية: كل استدعاء يبني منسقاً جديداً داخلياً. وهي مناسبة لقيمة واحدة فقط، وغير صالحة للقوائم.
+
+قم بتخزينها مؤقتاً بالاعتماد على دمج كود اللغة والخيارات:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## خطأ المنطقة الزمنية الذي لا يظهر إلا في بيئة الإنتاج
+
+هذه المشكلة تستنزف ساعات طويلة من وقت المطورين. يقوم الخادم بتصيير التاريخ عبر SSR، ثم يستلمه المتصفح لعمل الهيدرة، فيلقي React خطأ عدم تطابق الهيدرة لأن النص المُولد من الخادم اختلف عن المتصفح.
+
+السبب هو أن `Intl.DateTimeFormat` تستخدم المنطقة الزمنية لجهاز التشغيل إذا لم يتم تحديدها بوضوح. خادم الإنتاج يعمل بتوقيت UTC، بينما حاسوب التطوير يعمل بتوقيت محلي مختلف. لذا يظل الخطأ خفياً محلياً ولا ينفجر إلا في الإنتاج.
+
+```ts
+// الخادم بـ UTC والمتصفح بـ UTC+3 يختلفان في النتيجة، مما يفشل الهيدرة:
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// كلاهما يتطابق تماماً:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+ثلاثة حلول عملية:
+
+- **تثبيت المنطقة الزمنية** على الخادم وتمريرها صراحة. حل حاسم ومستقر، لكن يرى الجميع توقيت UTC.
+- **التصيير على العميل فقط**، مع ترك نص بديل محايد في الخادم. دقيق لكل مستخدم ولكنه قد يسبب وميضاً بصرياً سريعاً.
+- **تخزين المنطقة الزمنية للمستخدم** وتمريرها في الخادم والعميل معاً. الخيار الأمثل ولكن يتطلب تجهيزاً برمجياً إضافياً.
+
+أياً كان اختيارك، حدد خاصية `timeZone` دائماً وبشكل صريح لأي تاريخ يتم تصييره في الخادم والعميل معاً. فالتاريخ بدون منطقة زمنية هو تاريخ يحمل قيمتين مختلفتين.
+
+## العملة تحتاج إلى كود عملة، وليس إلى مجرد لغة
+
+اللغة والعملة مفهومان منفصلان. تحديد `fr-FR` لا يعني حتماً التعامل باليورو: فقد يطالع مستخدم فرنسي فاتورة بالدولار الأمريكي.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+تتحكم اللغة في الفواصل، وتجميع الأرقام، وموضع رمز العملة. بينما تأتي العملة نفسها من بيانات المعاملة. استنتاج العملة من كود اللغة خطأ محاسبي مباشر.
+
+انتبه أيضاً لخيار `currencyDisplay`. في الواجهات التي تجتمع فيها عدة عملات تشترك برمز الدولار ($)، فإن قيمة `"code"` تزيل أي لبس بين الدولار الأمريكي والكندي والأسترالي.
+
+## الوقت النسبي أكثر وضوحاً من التوقيت المطلق
+
+بالنسبة للأحداث الأخيرة، فإن "منذ ساعتين" أسهل في القراءة من الطابع الزمني الثابت، وتتولى `Intl.RelativeTimeFormat` توطين ذلك بدقة.
+
+```ts
+new Intl.RelativeTimeFormat("ar", { numeric: "auto" }).format(-1, "day");
+// "أمس"
+```
+
+خاصية `numeric: "auto"` هي التي تنتج "أمس" بدلاً من التعبير الرقمي الجاف "قبل يوم واحد".
+
+## ما تقدمه مكتبة Intlayer
+
+تغلف Intlayer هذه الواجهات في دوال مساعدة ذاتية التخزين المؤقت، لتغنيك عن إدارة خرائط الذاكرة يدوياً، وتطبق اللغة الحالية تلقائياً دون الحاجة لتمريرها في كل موضع استدعاء.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1,234.5"
+currency(1234.5, { currency: "EUR" }); // "1,234.50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "منذ ساعتين"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 كيلومتر"
+compact(1200); // "1.2 ألف"
+list(["تفاحة", "موزة", "برتقالة"]); // "تفاحة، موزة، وبرتقالة"
+```
+
+تقبل الدالة `date()` الإعدادات الجاهزة (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`). وتوجد أدوات مقابلة لـ React و Vue على هيئة hooks و composables تستخرج اللغة النشطة مباشرة من السياق.
+
+هذه مجرد طبقة تخزين مؤقت ومطابقة للغة مبنية فوق الواجهة القياسية للمنصة، أما سلوك التنسيق الفعلي فهو نابع من `Intl`. راجع كافة التفاصيل في [توثيق أدوات التنسيق](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/formatters.md).
+
+## أخطاء شائعة
+
+- **استدعاء `toLocaleDateString()` دون تمرير لغة.** يعتمد على لغة النظام المضيف، والتي تتغير في الخوادم بحسب ضبط الحاوية.
+- **التنسيق داخل الحلقات التكرارية دون تخزين مؤقت.** إنشاء الكائن يستهلك معظم وقت المعالجة.
+- **تجاهل `timeZone` في التواريخ المشتركة بين الخادم والعميل.** يسبب أخطاء هيدرة يستحيل إعادة إنتاجها محلياً.
+- **تخمين العملة من اللغة.** `fr-FR` لا تعني اليورو تلقائياً.
+- **استخدام `sort()` العادية على نصوص الواجهة.** استعن دائماً بـ `Intl.Collator`.
+- **كتابة أسماء الشهور أو الأيام بشكل ثابت في الكود.** جميعها مسجلة وموثوقة بالفعل في CLDR لكل لغة.
+- **الإبقاء على `numeric: "always"` في الوقت النسبي.** يؤدي لظهور "قبل يوم واحد" بدلاً من "أمس".
+
+## للمزيد من القراءة
+
+- [أدوات التنسيق ومساعدات اللغة: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/formatters.md)
+- [مرجع الإعدادات](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md)
+- [تقارير المقارنة المعيارية عبر أطر العمل](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/benchmark/index.md)
+- [محول التوافق مع react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compat/react-intl.md)
+- [تنسيق رسائل ICU: الجمع، الخيارات، ونماذج الأرقام](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/icu_message_format.md)
+- [استراتيجيات اختبار الترجمات والتنسيق وقواعد الجمع](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/i18n_testing_strategies.md)
+- [ما يغطيه التدويل فعلياً](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/what_is_internationalization.md)

package/blog/ar/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "كيفية اكتشاف الترجمات المفقودة قبل أن يكتشفها مستخدموك"
+description: الترجمات المفقودة تفشل بصمت دون تنبيه. لماذا يخفيها التراجع التلقائي (Fallback)، والطبقات الأربع الفعالة للاكتشاف، وكيف تفشل عملية البناء عند وجود مفتاح غير مترجم.
+keywords:
+  - العثور على الترجمات المفقودة
+  - مفاتيح الترجمة المفقودة
+  - تدقيق i18n
+  - نصوص غير مترجمة
+  - تغطية الترجمة
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# كيفية اكتشاف الترجمات المفقودة قبل أن يكتشفها مستخدموك
+
+نادراً ما تؤدي الترجمة المفقودة إلى ظهور خطأ استثنائي أو توقف التطبيق. بناءً على إعداداتك، إما أنها تعرض النص الإنجليزي لمستخدم ياباني، أو تطبع `checkout.summary.total` مباشرة على الشاشة في بيئة الإنتاج. كلا الأمرين يتم شحنه في الإصدار، ويجتاز مراجعة الكود، ويكتشفه العميل بدلاً من أن تكتشفه أنت.
+
+## جدول المحتويات
+
+<TOC/>
+
+## هذا ينطبق مهما كانت المكتبة التي تستخدمها
+
+لا شيء هنا محصور ببيئة برمجية معينة. تعمل طبقات الاكتشاف أدناه بنفس الطريقة على i18next أو react-i18next أو next-intl أو react-intl أو vue-i18n أو next-translate أو Lingui، لأنها تحل المفاتيح وتفشل بنفس الآلية.
+
+الأدوات قابلة للنقل أيضاً. إذا كانت نصوصك موجودة اليوم في كتالوجات JSON، فإن [إضافة Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/plugins/sync-json.md) توجه Intlayer إلى تلك الملفات، لتحصل على أوامر التدقيق، والتعبئة، والاختبار دون نقل محتواك أو تغيير استيراد واحد:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // أو "icu" لمكتبات next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+إذا كنت تفضل الإبقاء على واجهة وقت التشغيل كما هي، فإن [محولات التوافق](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compat/index.md) تعيد تسمية `useTranslation` و `$t` وما شابهها على مستوى أداة الحزم (Bundler). في كلا الحالتين، تعامل مع الأوامر أدناه كتطبيق عملي للفكرة وليس كشرط إلزامي.
+
+## لماذا تكون الترجمات المفقودة غير مرئية؟
+
+تحل كل مكتبة i18n المفاتيح عبر نفس السلسلة: البحث في اللغة النشطة، التراجع إلى اللغة الافتراضية، وإذا فشل ذلك، إرجاع المفتاح نفسه كنص. هذه الخطوة الأخيرة هي جوهر المشكلة. لا يوجد خطأ برمجي، ولا تحذير في بيئة الإنتاج، ولا اختبار يفشل، لأن مسار العمل لا يتعامل مع المفتاح المفقود كحالة غير طبيعية.
+
+آلية التراجع التلقائي (Fallback) تزيد الأمر سوءاً. فالصفحة التي تظهر باللغة الإنجليزية في صمت تبدو سليمة تماماً للمطور الناطق بالإنجليزية ولجميع الاختبارات الآلية. المشكلة لا تظهر إلا للشخص الذي لا يستطيع قراءة الإنجليزية.
+
+لذا فإن السؤال ليس "كيف أتعامل مع الترجمات المفقودة أثناء وقت التشغيل". بل هو "كيف أجعل دمج فرع يحتوي على ترجمة مفقودة أمراً مستحيلاً".
+
+## الطبقات الأربع التي يمكنك الإمساك بها من خلالها
+
+تلتقط كل طبقة ما تعجز عنه الطبقات الأخرى. وتحتاج عملياً إلى أكثر من واحدة.
+
+| الطبقة          | تكتشف                                        | تفوت                                           |
+| :-------------- | :------------------------------------------- | :--------------------------------------------- |
+| الأنواع (Types) | مفاتيح غير موجودة على الإطلاق                | مفتاح موجود ولكنه غير مترجم في اللغة اليابانية |
+| الفحص (Lint)    | نصوص ثابتة لم يتم استخراجها للترجمة أبداً    | مفاتيح مفقودة من كتالوج معين                   |
+| التدقيق (Audit) | تغطية اللغات عبر كل المفاتيح المصرح بها      | نصوص لم يتم تحويلها إلى نصوص قابلة للترجمة     |
+| اختبارات العرض  | مفاتيح تم العثور عليها لكنها تُعرض بشكل خاطئ | كل ما لم يشمله اختبار برمجي                    |
+
+الفجوة التي تقع فيها معظم الفرق هي الصف الثالث: فهم يعلمون أن مفاتيحهم صالحة برمجياً، لكن لا توجد أداة تتحقق من أن جميع اللغات الثماني عشرة تحتوي على ترجمات فعلية.
+
+## الطبقة الأولى: جعل المفتاح نوعاً (Type) وليس مجرد نص
+
+`t("checkout.summry.total")` خطأ إملائي يمر عبر مرحلة البناء والترجمة البرمجية دون اعتراض. إذا كانت مفاتيحك نصوصاً عادية، فكل إعادة تسمية تمثل مخاطرة في الإنتاج، وكل عملية حذف تترك وراءها مفاتيح مهجورة.
+
+المفاتيح المعرفة بأنواع بيانات صارمة تحول هذه المشكلة إلى خطأ بناء يوقف الكود. يدعم `react-i18next` ذلك عبر دمج التصريحات، ويستنتجه `next-intl` من بنية الرسائل، ويستخرج Lingui المعرفات من نصوص المصدر، وينشئ Intlayer أنواعاً دقيقة من ملفات الإعلان. كلها تؤدي الغرض؛ الفارق يكمن في مقدار الجهد اللازم للضبط.
+
+هذه الطبقة ضرورية ولكنها غير كافية بمفردها. فالأنواع تضمن صحة هيكل الكتالوج الافتراضي، لكنها لا تضمن وجود قيمة للمفتاح في اللغة الكورية مثلاً.
+
+## الطبقة الثانية: فحص النصوص التي لم تتحول لمفاتيح (Linting)
+
+الترجمة التي لا تجدها غالباً ما تكون نصاً لم يتم نقله للملفات المترجمة إطلاقاً. النص المكتوب مباشرة داخل المكون لا يمكن لأي تدقيق كتالوجات اكتشافه، لأنه ببساطة غير مسجل في النظام.
+
+تعالج إضافة ESLint الخاصة بـ Intlayer هذه النقطة عبر قاعدة `no-raw-text`، بالإضافة إلى `no-unused-content` للحالة المعاكسة: محتوى تم التصريح عنه ولم يعد مستخدماً في أي مكان.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+قاعدة `no-unused-content` تمنع تضخم الكتالوجات بلا نهاية. فالمفاتيح المهجورة لا تكسر الكود، لكنها ترفع فواتير شركات الترجمة. تجد القائمة الكاملة للقواعد في [توثيق إضافة ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/eslint.md).
+
+## الطبقة الثالثة: تدقيق تغطية اللغات
+
+هذه هي الطبقة التي تجيب على السؤال الأهم. يوفرها Intlayer كأمر عبر واجهة الأوامر:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+يقوم الأمر بقراءة اللغات المحددة والقواميس، ثم يوضح بدقة أي المفاتيح تفتقر إلى أي لغات، وفي أي ملف تقع.
+
+تفصيلة هامة قبل ربطها في مسارات العمل: **تطبع واجهة الأوامر تقريراً ولكنها تنهي التنفيذ بالرمز صفر (نجاح).** فإذا وضعتها في الـ CI على أمل إيقاف البناء، ستحصل على علامة خضراء وتقرير طويل لن يقرأه أحد. لمنع البناء وإيقافه، استخدم واجهة البرمجة التطبيقية أدناه.
+
+## الطبقة الرابعة: التأكيد الصريح في مجموعة الاختبارات
+
+توفر لك دالة `listMissingTranslations()` نفس تقرير التدقيق كبيانات برمجية، وهو المطلوب تماماً لبوابة فحص البناء.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("لا توجد لغات مطلوبة مفقودة", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+تعيد الدالة ثلاثة حقول جوهرية:
+
+- `missingTranslations`: المفاتيح واللغات المفقودة واسم الملف لكل منها. يُفضل طباعته عند فشل الاختبار.
+- `missingLocales`: اتحاد كافة اللغات التي ينقصها محتوى عبر جميع المفاتيح.
+- `missingRequiredLocales`: محصور فقط في `requiredLocales` المحددة في إعداداتك، أو جميع اللغات إن لم تُحدد.
+
+## `requiredLocales` تجعل الفحص قابلاً للتطبيق العملي
+
+دعم ثماني عشرة لغة لا يعني إلزامية اكتمالها جميعاً بنسبة 100% لنشر الكود. تضع معظم الفرق تصنيفاً يوقف النشر وتصنيفاً يتم العمل عليه تدريجياً.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+دون `requiredLocales`، تصبح كل لغة معلنة ملزمة للبناء ويتعطل النشر انتظاراً لآخر ترجمة، مما ينتهي بقيام الفريق بتعطيل الفحص كلياً.
+
+## كشف الفجوات الموجودة بالفعل في بيئة الإنتاج
+
+تمنع الطبقات السابقة حدوث فجوات جديدة. وللتطبيقات العاملة بالفعل، تفيدك خطوتان:
+
+**التوطين الزائف (Pseudolocalization).** استخدم لغة تجريبية يتم فيها تشويه كل نص مثل `[!!! Ĉĥéçķöũţ !!!]`. أي نص يظهر بالإنجليزية العادية هو نص مكتوب بشكل ثابت في الكود. يكشف ذلك في عشر دقائق ما يعجز عنه تدقيق الكتالوجات.
+
+**الزحف الآلي على موقعك (Crawling).** إذا كنت توفر روابط مخصصة لكل لغة، اطلب عينة من الصفحات وابحث في كود الـ HTML عن النصوص الإنجليزية. ظهور "Add to cart" في رابط `/ja/` يشير فوراً لترجمة مفقودة أو تراجع غير مقصود.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## ملء الفجوات
+
+بمجرد تحديد ما ينقصك، يملأ الأمر `intlayer fill` الخانات الشاغرة، ويمكن للخيار `autoFill` توليد ملفات اللغات بمجرد كتابة المحتوى. راجع [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/autoFill.md).
+
+كن واقعياً: الترجمة الآلية تحول النقص **المرئي** إلى نقص **غير مرئي**. المفتاح أصبح يحمل نصاً والاختبار بات أخضر، ولكن لم يقرأ أحد ذلك النص. استعن بها لإنجاز الإطلاق، لكن دقق النصوص الحساسة بشرياً دائماً.
+
+## أخطاء شائعة
+
+- **التعامل مع الـ Fallback كشبكة حماية.** هو مجرد حل إسcleaافي للعرض، والنص الإنجليزي الصامت خطأ لا يُبلغ عنه أحد.
+- **الاعتماد على تقرير CLI لإيقاف CI.** يخرج الأمر دائماً بالرمز صفر. استخدم التأكيد في الاختبارات.
+- **إلزامية كافة اللغات كشرط وحيد.** يؤدي لحذف الفحص عند أول تعطل للإطلاق.
+- **فحص الكتالوجات وإهمال الشاشة المعروضة.** النصوص الثابتة لا تظهر في الكتالوجات أصلاً.
+- **اختبار اللغة الافتراضية فقط.** اللغة الوحيدة المضمون عدم نقصها.
+- **الاكتفاء بالتعبئة الآلية كحل نهائي.** فحص أخضر ونصوص رديئة لم يقرأها بشر.
+
+## للمزيد من القراءة
+
+- [اختبار المحتوى: تدقيق CLI، واجهة برمجة التطبيقات البرمجية وتأكيدات الواجهة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/testing.md)
+- [قواعد إضافة ESLint، بما فيها `no-raw-text` و `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/eslint.md)
+- [autoFill: إنشاء ملفات الإعلان لكل لغة](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/autoFill.md)
+- [مرجع الإعدادات: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md)
+- [تقارير المقارنة المعيارية عبر أطر العمل](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/benchmark/index.md)
+- [محول التوافق مع i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/compat/i18next.md)
+- [ما يشمله التدويل الفعلي](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/what_is_internationalization.md)
+- [التدويل على مستوى المكونات مقابل التدويل المركزي](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ar/per-component_vs_centralized_i18n.md)