@intlayer/docs 9.5.6 → 9.5.8

package/blog/ar/is_intlayer_lighter_than_paraglide.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2026-09-23
+updatedAt: 2026-09-23
+title: هل Intlayer أخف من Paraglide؟
+description: يبدو Paraglide شبه مجاني في اختبارات أداء التدويل (i18n) لأن كوده يتم توليده مباشرة في مستودع مشروعك. نوضح هنا إلى أين يذهب ذلك الحجم فعلياً، ولماذا يكلفك فحص اللغة لكل عقدة أداءً إضافياً، وكيف يشحن التحميل الديناميكي في Intlayer لغة واحدة بدلاً من جميع اللغات.
+keywords:
+  - Paraglide
+  - Intlayer
+  - تدويل
+  - i18n
+  - Bundle size
+  - Tree shaking
+  - Benchmark
+  - Blog
+slugs:
+  - blog
+  - is-intlayer-lighter-than-paraglide
+author: aymericzip
+---
+
+# هل Intlayer أخف من Paraglide؟
+
+نعم.
+
+يحظى `Paraglide` بسمعة جيدة باعتباره أخف حلول التدويل المتاحة، وللوهلة الأولى يتفق [اختبار الأداء](https://intlayer.org/ar/doc/benchmark/tanstack) مع ذلك: فحجم مكتبته يقارب الصفر. لكن حجم مكتبة يقارب الصفر لا يعني إرسال صفر بايت إلى المتصفح. هذا يعني ببساطة أن البايتات تستقر في مكان لا ترصده تلك المعايير.
+
+<TOC/>
+
+## النقاط الرئيسية
+
+**حجم المكتبة مخفي، وليس محذوفاً:**
+
+يولد Paraglide وقت التشغيل (runtime) ودوال الرسائل الخاصة به مباشرة في قاعدة الكود (codebase) لديك. يتم شحن هذا الكود إلى المتصفح، لكنه يُحسب ككود _خاص بك_، وليس ككود للمكتبة.
+
+**غياب الـ Provider ليس مكسباً مجانياً:**
+
+كل استدعاء للدالة `m.my_key()` يحدد اللغة بنفسه، حيث يقرأ ملف تعريف الارتباط (cookie) أو التخزين المحلي لكل عقدة يتم تصييرها (render)، بدلاً من قراءتها مرة واحدة فقط من السياق (context).
+
+**لا يوجد تحميل ديناميكي (Dynamic Loading):**
+
+يستورد Paraglide كل لغات الرسالة في حزمة العميل (client bundle). بينما يقوم Intlayer مع خيار `importMode: 'dynamic'` أو `'fetch'` بتحميل اللغة التي يتم عرضها حالياً فقط.
+
+**الـ Tree Shaking ليس مضموناً دائماً:**
+
+في بعض اختبارات الأداء لدينا، لم تعمل ميزة Tree Shaking المعلن عنها في Paraglide بالشكل المطلوب. نوصي بفحص الحزمة الخاصة بك.
+
+## أين يذهب حجم Paraglide الفعلي؟
+
+في تقارير المقارنة المعيارية، يقيس مقياس "حجم المكتبة" الـ provider والـ hooks لكل مكتبة i18n في مكون فارغ، قبل إضافة أي محتوى.
+
+| المكتبة (TanStack Start)      | حجم المكتبة (gz) | حجم المكتبة (min) |
+| ----------------------------- | ---------------- | ----------------- |
+| `@inlang/paraglide-js@2.15.1` | 1.8 KB           | 4.5 KB            |
+| `react-intlayer@9.5.1`        | 5.0 KB           | 15.2 KB           |
+
+إذا قرأت هذه الأرقام بمعزل عن السياق، يبدو أن Paraglide هو الفائز. لكن Paraglide عبارة عن مترجم (compiler): فهو يقرأ ملفات `messages/*.json` الخاصة بك وينشئ مجلد `paraglide/` داخل مستودع مشروعك، ويحتوي على ملف `runtime.js` (اكتشاف اللغة، استراتيجيات الكوكيز والتخزين، وتوطين الروابط) ودالة جافاسكريبت واحدة لكل رسالة.
+
+```bash
+src/paraglide/
+├── runtime.js      # اكتشاف اللغة، الاستراتيجيات، مساعدات الروابط
+├── server.js
+├── messages.js     # إعادة تصدير كافة الرسائل
+└── messages/
+    ├── _index.js
+    ├── en.js
+    └── fr.js
+```
+
+نظراً لأن هذا الكود يستقر داخل مجلد `src/` الخاص بك وتقوم باستيراده بمسار نسبي، فإن أداة الحزم (bundler) تنسبه إلى تطبيقك، وليس إلى حزمة خارجية في `node_modules`. لذلك يُظهر عمود حجم المكتبة رقماً يقارب الصفر، في حين أن نفس المنطق البرمجي يُشحن فعلياً ضمن حزمة صفحتك.
+
+توليد الكود ليس فكرة سيئة بحد ذاته: فوقت التشغيل المولد لا يتضمن سوى المنطق الذي تتطلبه إعداداتك (استراتيجية البادئة، الكوكيز مقابل التخزين المحلي، إلخ). ويحقق Intlayer نفس النتيجة بأسلوب مختلف، عن طريق حقن متغيرات البيئة أثناء مرحلة البناء، مما يسمح لأداة الحزم بحذف الفروع البرمجية التي لا تستخدمها إعداداتك. كلا الأسلوبين ينتهي بهما الأمر أخف بما يتراوح بين 3 إلى 10 مرات مقارنة بـ `i18next` أو `next-intl`.
+
+لذا، فإن المقارنة العادلة ليست حجم المكتبة المجرد. بل هي **كمية الجافاسكريبت المرسلة فعلياً لكل صفحة**.
+
+## وزن الصفحة المقاس فعلياً
+
+تطبيق TanStack Start، يتكون من 10 صفحات، تم القياس على مساري `en` و `fr`، بضغط gzip:
+
+| الإعداد                            | متوسط JS للصفحة (gz) | الزيادة عن الأساس | تسريب اللغات | تسريب الصفحات الأخرى |
+| ---------------------------------- | -------------------- | ----------------- | ------------ | -------------------- |
+| الأساس (بدون i18n)                 | 111.0 KB             | -                 | 0.0%         | 0.0%                 |
+| `paraglide` (أي استراتيجية)        | 125.1 KB             | +14.1 KB          | 49.7%        | 0.0%                 |
+| `intlayer` (`importMode: static`)  | 125.8 KB             | +14.8 KB          | 50.0%        | 0.0%                 |
+| `intlayer` (`importMode: dynamic`) | **118.6 KB**         | **+7.6 KB**       | **0.0%**     | **0.0%**             |
+
+تطبيق Next.js 16 App Router، نفس التطبيق:
+
+| الإعداد            | متوسط JS للصفحة (gz) | الزيادة عن الأساس |
+| ------------------ | -------------------- | ----------------- |
+| الأساس (بدون i18n) | 141.0 KB             | -                 |
+| `paraglide-next`   | 155.3 KB             | +14.3 KB          |
+| `next-intlayer`    | **141.3 KB**         | **+0.3 KB**       |
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+> البيانات الكاملة متوفرة في [تقرير مقارنة TanStack Start](https://intlayer.org/ar/doc/benchmark/tanstack) و[تقرير مقارنة Next.js](https://intlayer.org/ar/doc/benchmark/nextjs). يمكن فحص كل حزمة في [مستودع اختبارات الأداء](https://github.com/intlayer-org/benchmark-i18n).
+
+هناك نقطتان واضحتان:
+
+- في الوضع الثابت (`static`)، يرسل Intlayer نفس المحتوى تقريباً مقارنة بـ Paraglide (125.8 KB مقابل 125.1 KB). وهذا أمر متوقع: فكلاهما يضم جميع لغات الرسائل التي تستخدمها الصفحة.
+- يظل Paraglide عند 125.1 KB مهما كانت الاستراتيجية المستخدمة، لأنه لا يحتوي على وضع ديناميكي. كل سطر في الجدول أعلاه يمثل النمط الثابت.
+
+## غياب الـ Provider: فكرة تبدو جذابة ولكنها ليست كذلك
+
+لا يتطلب Paraglide استخدام Provider. كل ما تفعله هو استيراد الرسالة واستدعاؤها:
+
+```tsx fileName="Hero.tsx"
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => (
+  <section>
+    <h1>{m.hero_title()}</h1>
+    <p>{m.hero_description()}</p>
+    <button>{m.hero_cta()}</button>
+  </section>
+);
+```
+
+لا سياق، لا غلاف، ولا خطافات (hooks). يبدو الأمر أبسط. لكن اللغة لا تزال بحاجة إلى تحديد مصدرها. تبدو كل دالة رسالة مولدة تقريباً على هذا النحو (بشكل مبسط):
+
+```js fileName="paraglide/messages/_index.js"
+export const hero_title = (inputs = {}, options = {}) => {
+  const locale = options.locale ?? getLocale(); // يتم تحديدها عند كل استدعاء
+
+  if (locale === "en") return en.hero_title(inputs);
+  if (locale === "fr") return fr.hero_title(inputs);
+  // ...فرع برمجي لكل لغة
+};
+```
+
+وتقوم `getLocale()` بفحص الاستراتيجيات المحددة (الكوكيز، التخزين المحلي، الرابط، اللغة الأساسية) لمعرفة اللغة الحالية. هذا يعني أن كل عقدة نصية تصيّرها (`<>{m.my_key()}</>`) تقوم بتشغيل عملية تحديد لغة مستقلة، بما في ذلك قراءة `document.cookie` في المتصفح. صفحة تحتوي على 200 نص مترجم تقوم بتحديد اللغة 200 مرة في كل عملية تصيير، وتتكرر العملية مع كل إعادة تصيير.
+
+في المقابل، فإن المكتبة التي تعتمد على Provider تقرأ اللغة **مرة واحدة فقط**، وتخزنها في سياق (أو signal، أو store)، وتقرأ كل عقدة قيمة مخزنة مسبقاً في الذاكرة. يكلف الـ Provider بضع مئات من البايتات فقط. وتخطي استخدامه يستهلك دورات المعالج مع كل تصيير، وهو ما يتضح جلياً في اختبار الأداء: فأوقات تحميل الصفحة وسرعة تبديل اللغة في Paraglide تتأخر باستمرار مقارنة بـ Intlayer على TanStack Start (22.1 مللي ثانية مقابل 14.6 مللي ثانية في تحميل الصفحة، و 4.3 مللي ثانية مقابل 3.2 مللي ثانية في الاستجابة E2E).
+
+## تجربة المطور (DX)
+
+مصدر الحقيقة في Paraglide هو ملفات JSON، لكنك لا تستورد ملف الـ JSON مطلقاً، بل تستورد ملف الـ `.js` المولد:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="Paraglide" value="paraglide">
+
+```json fileName="messages/en.json"
+{
+  "hero_title": "Ship your app in every language"
+}
+```
+
+```json fileName="messages/ar.json"
+{
+  "hero_title": "انشر تطبيقك بكل اللغات"
+}
+```
+
+```tsx fileName="Hero.tsx"
+// لا يوجد هذا الملف إلا بعد أن يعيد المترجم توليده من ملف الـ JSON
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => <h1>{m.hero_title()}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="Hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      ar: "انشر تطبيقك بكل اللغات",
+      en: "Ship your app in every language",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+هذا النمط في العمل له ثمن:
+
+- كل تعديل على ملف JSON يتطلب إعادة توليد قبل أن يتم التعرف على الاستيراد أو تتحدث الأنواع (types).
+- مجلد `paraglide/` المولد إما أن يتم إدراجه في git (مما يؤدي لتعارضات دمج في الملفات المولدة مع كل طلب سحب PR يمس النصوص)، أو يتم تجاهله (مما يتطلب خطوة توليد إلزامية قبل كل فحص للأنواع أو اختبار أو مهمة CI).
+- كل نص يتحول إلى استدعاء دالة. وتتحول الثوابت إلى `m.key()` في كل مكان، حتى في الأماكن التي تكفي فيها قيمة ثابتة بسيطة.
+
+## Tree Shaking: افحص الحزمة الخاصة بك
+
+الوعد الأساسي لـ Paraglide هو أن الرسائل غير المستخدمة يتم التخلص منها عبر الـ Tree Shaking لأن كل رسالة تصدر كعنصر مستقل. وفي اختبار Svelte + Vite، عملت هذه الميزة كما هو متوقع.
+
+لكن في بيئات أخرى، لم يتحقق ذلك. ففي اختبارنا على [Next.js](https://intlayer.org/ar/doc/benchmark/nextjs)، زادت صفحات Paraglide بمقدار 14 KB مقارنة بالتطبيق الأساسي، بينما أضاف `next-intlayer` فقط 0.3 KB. كما أظهرت اختبارات سابقة على TanStack Start تسرب رسائل من صفحات أخرى إلى حزمة المسار الحالي.
+
+يعتمد الـ Tree Shaking على أداة الحزم لديك (Turbopack، Rolldown، Rollup)، وعلى طريقة استيراد الرسائل (`import { m }` مقابل `import * as m`)، وعلى تحليل الآثار الجانبية (side-effects). إذا اخترت Paraglide لصغر حجمه، افتح أداة فحص الحزم وتأكد من تحقق ذلك في تطبيقك الفعلي.
+
+## غياب التحميل الديناميكي
+
+هذا هو العائق البنيوي الأبرز. لا يمتلك Paraglide وسيلة لتحميل لغة واحدة في كل مرة: فكل دالة رسالة تستورد تنفيذ كل اللغات بشكل ثابت، مما يجعل جميع اللغات تنتهي داخل حزمة العميل الخاصة بك.
+
+عند دعم لغتين، يتم هدر نصف بيانات الترجمة المنقولة، وهو ما يطابق نسبة تسريب اللغات المقدرة بـ ~50% أعلاه. ومع 10 لغات، يرتفع الهدر إلى 90%. ومع 30 لغة، يصل إلى 97%.
+
+والانتقال إلى التحميل الديناميكي لن يحل المشكلة أيضاً: فمع وجود دالة مستقلة لكل رسالة، فإن تحميل كل دالة بشكل كسول سيعني إطلاق آلاف الطلبات عبر الشبكة.
+
+يتيح لك Intlayer حرية الاختيار، سواء على المستوى العام للتطبيق أو لكل قاموس على حدة:
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic", // 'static' | 'dynamic' | 'fetch'
+  },
+};
+
+export default config;
+```
+
+| `importMode` | ما يتم إرساله إلى العميل                            | مقارنة بـ Paraglide            |
+| ------------ | --------------------------------------------------- | ------------------------------ |
+| `static`     | جميع لغات القواميس التي تستخدمها الصفحة             | نفس المحتوى نظرياً             |
+| `dynamic`    | اللغة الحالية فقط، محملة بكسل لكل قاموس             | **أخف بـ N مرة** مع وجود N لغة |
+| `fetch`      | اللغة الحالية فقط، مجلوبة عبر واجهة برمجة Live Sync | **أخف بـ N مرة** مع وجود N لغة |
+
+بفضل [التحويل أثناء البناء](https://intlayer.org/ar/doc/concept/bundle-optimization) وخيار `importMode: 'static'`، يحمّل Intlayer نظرياً نفس المحتوى تماماً مثل Paraglide. ومع استخدام `'dynamic'` أو `'fetch'`، فإنه يحمّل فقط ما تتطلبه اللغة الحالية: لتطبيق يدعم N لغة، تصبح حمولة الترجمة أصغر بـ N مرة مقارنة بـ Paraglide.
+
+## متى يظل Paraglide خياراً مناسباً؟
+
+<AccordionGroup>
+<Accordion header="تطبيقات Svelte + Vite مع عدد قليل من اللغات">
+
+إذا كانت بيئة تطويرك تعتمد على Svelte مع Vite وتدعم لغتين أو ثلاث، فإن الـ Tree Shaking يعمل كما ينبغي ويبقى العبء الإضافي للغات محدوداً.
+
+</Accordion>
+<Accordion header="سير العمل القائم حالياً على inlang">
+
+إذا كان فريقك يستخدم بالفعل منظومة inlang (مثل Fink و Sherlock وإضافات صيغ الرسائل)، فإن Paraglide يتكامل معها بشكل أصيل وسلس.
+
+</Accordion>
+</AccordionGroup>
+
+## جربه على تطبيقك
+
+تحقق من حجم تطبيقك الحي ومستوى تسريب اللغات باستخدام أداة [i18n SEO Scanner](https://intlayer.org/i18n-seo-scanner) المجانية:
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+لتثبيت Intlayer:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+## قراءات إضافية
+
+- [اختبار أداء i18n في TanStack Start](https://intlayer.org/ar/doc/benchmark/tanstack)
+- [اختبار أداء i18n في Next.js](https://intlayer.org/ar/doc/benchmark/nextjs)
+- [تحسين الحزم و `importMode`](https://intlayer.org/ar/doc/concept/bundle-optimization)
+- [كيفية اختيار مكتبة i18n المناسبة لـ React](https://intlayer.org/ar/blog/how-to-pick-react-i18n-library)
+- [دواعي ومبررات التدويل المعتمد على المترجم](https://intlayer.org/ar/blog/compiler-vs-declarative-i18n)

package/blog/ar/lingui_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "Lingui مقابل Intlayer: اختبار الأداء والمقارنة لعام 2026"
 description: "مقارنة بين مكتبتي تدويل (i18n) تعتمدان على المترجم تم قياسهما على Next.js وTanStack Start. حجم الحزمة، تسرب المحتوى، حجم المكونات، الترطيب، سرعة تبديل اللغة وتجربة المطور."
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui مقابل Intlayer | مقارنة أداء التدويل (i18n) في React وNext.js
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 تعد Lingui وIntlayer المكتبتين الوحيدتين في هذا الاختبار اللتين تعتمدان على **مترجم (Compiler)** بدلاً من بيئة تشغيل بحتة (Pure Runtime). تستخرج Lingui الرسائل من وحدات الماكرو في وقت البناء وتقوم بتجميع الكتالوجات لكل لغة. بينما يقوم Intlayer بتجميع القواميس لكل مكون مع تقليم الشجرة (Tree-shaking) لكل لغة. نظرياً، يجب أن تكون النتائج متقاربة، لكن الأرقام توضح أين يختلفان.
 
 البيانات مأخوذة من [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)، وهي مجموعة اختبارات مفتوحة المصدر تبني التطبيق نفسه مع كل مكتبة وتسجل ما يقوم المتصفح بتنزيله وتنفيذه فعلياً.
@@ -96,6 +98,10 @@ author: aymericzip
 
 ### النتائج على Next.js
 
+اختر المقاييس والمكتبات التي تهمك:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | المكتبة              | الاستراتيجية   | حجم المكتبة (gz) | متوسط JS للصفحة (gz) | تسرب اللغة | تسرب الصفحة | متوسط المكون (gz) | تفاعلية E2E | الترطيب |
 | -------------------- | -------------- | ---------------: | -------------------: | ---------: | ----------: | ----------------: | ----------: | ------: |
 | **base** (بدون i18n) | -              |           0.0 KB |             141.0 KB |       0.0% |        0.0% |            0.9 KB |     13.4 ms | 11.8 ms |
@@ -114,6 +120,15 @@ author: aymericzip
 - **تسرب اللغة المصدرية.** حتى في التهيئات المحسنة، **تتسرب 3-15% من نصوص `en` داخل صفحات `fr`**. تحتفظ وحدات ماكرو Lingui بالرسالة المصدرية كخيار احتياطي، مما يجعلها تستقر في الحزمة بجوار الترجمة. بينما يقوم Intlayer بحل الخيارات الاحتياطية أثناء البناء ويرسل اللغة النشطة فقط.
 - **تضخم حجم المكون في `scoped-dynamic`.** يبلغ متوسط حجم المكون المجمع بمعزل **152.6 كيلوبايت**، لأن كتالوج كل مسار يصبح قابلاً للوصول من المكون الذي يستورده. في المقابل يبلغ متوسط المكون نفسه مع `useIntlayer()` حوالي **6.9 كيلوبايت**.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> الجدول الكامل، لكل مكتبة واستراتيجية، في [تقرير قياس أداء Next.js](https://intlayer.org/ar/doc/benchmark/nextjs).
+
 ### النتائج على TanStack Start
 
 | المكتبة                    | الاستراتيجية   | حجم المكتبة (gz) | متوسط JS للصفحة (gz) | تسرب اللغة | تسرب الصفحة | متوسط المكون (gz) | تفاعلية E2E | الترطيب |
@@ -135,8 +150,19 @@ author: aymericzip
 - **يمتلك صف `static` في Intlayer نسبة تسرب 0% للصفحة تلقائياً** لأنه لا يتم تضمين سوى القواميس التي تستوردها مكونات الصفحة المعنية. سطر إعداد واحد (`importMode: 'dynamic'`) يزيل تسرب اللغة أيضاً.
 - **مكتبة `@intlayer/lingui`** تحافظ على صياغة ماكرو Lingui وتخدمها من قواميس Intlayer، مما يوفر مكونات أصغر حجماً (12.8 كيلوبايت) وترطيباً أسرع بكثير من Lingui الأصلي. إنها خطوة انتقال ممتازة وليست الوجهة النهائية.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> الجدول الكامل في [تقرير قياس أداء TanStack Start](https://intlayer.org/ar/doc/benchmark/tanstack).
+
 ## لماذا هذا الفارق؟ مترجمان بوحدتي عمل مختلفتين
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 تعتمد كلتا المكتبتين على الترجمة البرمجية (Compilation)، لكن الفارق يكمن في **ما** تقومان بترجمته.
 
 **يقوم Lingui بتجميع الكتالوجات.** يتم استخراج الماكرو في الكود المصدري إلى ملف `.po` لكل لغة، ثم تجميعه في وحدة JS لكل لغة. وحدة العمل هنا هي **اللغة**. ولتقسيمها بشكل أدق، حسب المسار أو المكون، يلزم إنشاء كتالوجات متعددة وتعديل `lingui.config.ts` والتحميل اليدوي لكل مسار. كائن `I18n` عام، وكل استدعاء لـ `useLingui()` يربط المكون به.
@@ -176,7 +202,9 @@ author: aymericzip
             └── about.content.ts
 ```
 
-لذلك فإن نمط `scoped-dynamic` هو نتاج بناء تلقائي لـ Intlayer، ومشروع تهيئة يدوي معقد لـ Lingui.
+لذلك فإن نمط `scoped-dynamic` هو نتاج بناء تلقائي لـ Intlayer، ومشروع تهيئة يدوي معقد لـ Lingui. وتتسع الفجوة على محورين في وقت واحد، الصفحات واللغات:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 > للحصول على أرقام صف `dynamic`، قم بضبط `dictionary.importMode: 'dynamic'` في ملف `intlayer.config.ts`. راجع [دليل تحسين الحزمة](https://intlayer.org/ar/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ author: aymericzip
 
 ### الإعداد
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="lingui.config.ts"
 import { defineConfig } from "@lingui/cli";
@@ -215,7 +244,8 @@ export const loadCatalog = async (locale: string) => {
 
 ثم إضافة `@lingui/babel-plugin-lingui-macro` (أو `@lingui/swc-plugin`) لأداة التحزيم، وتشغيل `lingui extract` بعد التعديل، و`lingui compile` قبل البناء، وتغليف الشجرة بـ `<I18nProvider i18n={i18n}>`.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -232,9 +262,12 @@ export default config;
 
 أضف `intlayer()` في `vite.config.ts` (أو `withIntlayer()` في `next.config.ts`) وغلف التطبيق بـ `<IntlayerProvider>`. لا حاجة لأي خطوة استخراج أو تجميع: تُبنى القواميس تلقائياً أثناء عمل أداة التحزيم.
 
+</Tab>
+</Tabs>
 ### المكونات
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```tsx fileName="src/components/Counter.tsx"
 import { useState } from "react";
@@ -258,7 +291,8 @@ export const Counter = () => {
 
 يعيش النص الإنجليزي في المكون؛ ويعيش الفرنسي في `src/locales/fr/messages.po` تحت معرف مجزأ بعد تشغيل `lingui extract`. نسيان تشغيله أو نسيان `compile` يعيد النص بصمت إلى الإنجليزية.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -297,11 +331,14 @@ export const Counter = () => {
 
 توجد كلتا اللغتين في ملف واحد بجوار المكون. غياب ترجمة `fr` يسبب خطأ في البناء، والمفتاح الخاطئ يسبب خطأ في TypeScript.
 
+</Tab>
+</Tabs>
 ### خارج المكونات
 
 البيانات الوصفية (Metadata)، والـ loaders، ودوال الخادم: أي مكان خارج شجرة React.
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { setupI18n } from "@lingui/core";
@@ -324,7 +361,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 إنشاء كائن `I18n` جديد لكل استدعاء، وتحميل الكتالوج يدوياً، واستخدام `msg` + `i18n._()` بدلاً من `t`. كما تشير [ملاحظات الاختبار](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md)، معرفة متى تستخدم `t` أو `` t` ` `` أو `i18n.t()` أو `msg` أو `<Trans>` "ليس بالأمر البديهي".
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { getIntlayer } from "intlayer";
@@ -336,6 +374,9 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## الاحتفاظ بماكرو Lingui مع قواميس Intlayer
 
 تعد حزمة `@intlayer/lingui` محولاً مباشراً لـ `@lingui/core` و`@lingui/react`. تواصل وحدات الماكرو التجميع كالمعتاد، بينما يتم توفير تنفيذ `i18n._()` من قواميس Intlayer، مع مزامنة ملفات `.po` للاحتفاظ بكتالوجاتك الحالية. تعمل خيارات وصيغ الجمع في ICU بالطريقة نفسها.
@@ -353,16 +394,82 @@ export default defineConfig({
 
 ## متى تختار أياً منهما؟
 
-- **اختر Lingui** إذا كنت بحاجة إلى **ICU MessageFormat** مع وحدات ماكرو نمطية، وكان المترجمون يعملون بملفات **`.po`** مع نظام TMS حالي، وتفضل وجود نصوص المصدر مضمنة داخل JSX، ولا يمانع فريقك إدارة عملية الاستخراج والتجميع وتوزيع الكتالوجات يدوياً.
-- **اختر Intlayer** إذا كنت تريد **محتوى بنطاق المكونات**، و**TypeScript صارماً**، و**أخطاء للمفاتيح المفقودة عند البناء**، و**تقليماً للشجرة وتحميلاً كسولاً تلقائياً بدون إعدادات**، ومكونات خفيفة، وترطيباً سريعاً، وتبديلاً فورياً للغة، وأدوات تحرير مدمجة (محرر مرئي، CMS، ترجمة بالذكاء الاصطناعي، خادم MCP).
-- **اختر `@intlayer/lingui`** إذا كنت تستخدم Lingui حالياً وتريد الانتقال تدريجياً إلى قواميس Intlayer دون تغيير صياغة وحدات الماكرو.
+<AccordionGroup>
+<Accordion header="اختر Lingui">
+
+أنت تريد **ICU MessageFormat** مع وحدات الماكرو المكتوبة، ومترجموك يعملون على ملفات **`.po`** مع مسار TMS حالي، وتفضل السلاسل المصدرية مضمنة داخل JSX، وفريقك مرتاح في إدارة تدفق الاستخراج والترجمة وتقسيم الكتالوجات. وحجم JS لكل صفحة تنافسي للغاية بمجرد إعداد التحميل الكسول.
+
+</Accordion>
+<Accordion header="اختر Intlayer">
+
+أنت تريد **محتوى بنطاق محدد على مستوى المكونات**، و**TypeScript صارماً**، و**أخطاء المفاتيح المفقودة وقت البناء**، و**tree-shaking وتحميلاً كسولاً دون جهد**، ومكونات خفيفة، وتفعيل hydration سريعاً، وتبديلاً فورياً للغة، وأدوات تحرير مدمجة ([المحرر المرئي](https://intlayer.org/ar/doc/concept/editor)، [نظام إدارة المحتوى CMS](https://intlayer.org/ar/doc/concept/cms)، [الترجمة بالذكاء الاصطناعي](https://intlayer.org/ar/doc/concept/auto-fill)، [خادم MCP](https://intlayer.org/ar/doc/mcp-server)). ملائم للغاية لقواعد الكود الكبيرة والمعيارية وأنظمة التصميم.
+
+</Accordion>
+<Accordion header="اختر @intlayer/lingui">
+
+أنت تستخدم Lingui حالياً وتريد الانتقال إلى قواميس Intlayer تدريجياً دون المساس بوحدات الماكرو. تظل كتالوجات `.po` الخاصة بك المصدر الوحيد للحقيقة عبر [إضافة مزامنة PO](https://intlayer.org/ar/doc/compatibility/lingui). تم قياسه جنباً إلى جنب في [Lingui مقابل @intlayer/lingui](https://intlayer.org/ar/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## الأسئلة الشائعة
+
+<FAQ>
+
+<Question title="Lingui تقوم بالترجمة والتجميع أيضاً، فلماذا تختلف النتائج إلى هذا الحد؟">
+
+لأن وحدة التجميع والترجمة تختلف تماماً. تجمع Lingui **كتالوجاً واحداً لكل لغة**: وكل ما هو دون ذلك (كتالوجات لكل مسار، التحميل الكسول، استبعاد النصوص الاحتياطية من الحزمة) يتطلب تكويناً يدوياً. بينما تجمع Intlayer **قاموساً واحداً لكل مكون**، مما يجعل تحديد نطاق المسار مخرجاً طبيعياً للبناء. لهذا السبب يزن مكون Lingui المترجم بشكل منفصل 58-153 كيلوبايت مقابل 6-8 كيلوبايت فقط في Intlayer.
+
+</Question>
+
+<Question title="لماذا لا يصل تسريب اللغات أبداً إلى 0% مع Lingui؟">
+
+تحتفظ وحدات الماكرو بالرسالة المصدرية كخيار احتياطي (fallback) في وقت التشغيل، مما يؤدي إلى شحن السلسلة الإنجليزية جنباً إلى جنب مع ترجمتها. يسجل الاختبار **3-15% من سلاسل `en` داخل صفحات `fr`** في كل إعداد مُحسَّن. بينما تعالج Intlayer الخيارات الاحتياطية أثناء البناء ولا ترسل سوى اللغة النشطة فقط.
+
+</Question>
+
+<Question title="هل كود JavaScript لكل صفحة في Lingui تنافسي حقاً؟">
+
+نعم، بل إنه يتفوق بفارق ضئيل على TanStack Start: 115.2 كيلوبايت في وضع `dynamic` مقابل 118.6 كيلوبايت لـ Intlayer. فالكتالوجات المجمعة ذات المعرفات المجزأة مدمجة وصغيرة. لكن التكلفة تظهر في جوانب أخرى: الـ Hydration يستغرق 28-34 مللي ثانية مقابل 11-14 مللي ثانية، وتبديل اللغة يستغرق **42 مللي ثانية** في إعداد `scoped-dynamic`.
+
+</Question>
+
+<Question title="هل يجب علي التخلي عن الماكرو للانتقال؟">
+
+لا. يحافظ `@intlayer/lingui` على ترجمة `` t`...` `` و `<Trans>` و `msg` و `plural` و `select` و `selectOrdinal` كما كانت تماماً؛ فقط ما يحلله `i18n._()` هو ما يتغير. احتفظ بـ `@lingui/babel-plugin-lingui-macro` أو `@lingui/swc-plugin` في البناء. راجع [وثائق توافق Lingui](https://intlayer.org/ar/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="ماذا عن خطوات الاستخراج والتجميع؟">
+
+تظل موجودة لوحدات الماكرو، وتختفي تماماً لمحتوى Intlayer الخاص. يتم بناء قواميس `.content.ts` تلقائياً عند تشغيل أداة الحزم، دون الحاجة إلى تشغيل أوامر CLI منفصلة، ويوقف أمر [`intlayer test`](https://intlayer.org/ar/doc/concept/cli) خط أنابيب CI عند وجود أي مفتاح مفقود بدلاً من الرجوع الصامت إلى السلسلة المصدرية.
+
+</Question>
+
+</FAQ>
 
 ## مقارنات ذات صلة
 
-- [next-intl مقابل Intlayer](https://intlayer.org/ar/blog/next-intl-vs-intlayer) (الاختبار نفسه)
-- [i18next مقابل Intlayer](https://intlayer.org/ar/blog/i18next-vs-intlayer) (الاختبار نفسه)
-- [vue-i18n مقابل Intlayer](https://intlayer.org/ar/blog/vue-i18n-vs-intlayer-benchmark) (الاختبار نفسه)
-- [المترجم مقابل التدويل التصريحي](https://intlayer.org/ar/blog/compiler-vs-declarative-i18n)
+نفس الاختبار المرجعي، مكتبات أخرى:
+
+- [next-intl vs Intlayer](https://intlayer.org/ar/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/ar/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ar/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ar/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ar/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+للمزيد من التفاصيل:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ar/blog/lingui-vs-intlayer-lingui), المحول المقاس على نفس التطبيق
+- [Compiler-driven vs declarative i18n](https://intlayer.org/ar/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/ar/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/ar/blog/icu-message-format)
+
+وثائق مرجعية:
+
+- [تقرير قياس أداء Next.js](https://intlayer.org/ar/doc/benchmark/nextjs) و [تقرير قياس أداء TanStack Start](https://intlayer.org/ar/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/ar/doc/compatibility/lingui)
+- [تحسين الحزمة](https://intlayer.org/ar/doc/concept/bundle-optimization) و [مترجم Intlayer](https://intlayer.org/ar/doc/compiler)
 
 ## نجوم GitHub