@intlayer/docs 9.5.2 → 9.5.3

package/blog/ar/vue-i18n_vs_intlayer-vue-i18n.md

@@ -0,0 +1,286 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: "vue-i18n مقابل @intlayer/vue-i18n: نفس الواجهة البرمجية، حزمة مختلفة"
+description: ما الذي يتغير عندما تحتفظ تطبيقات Vue 3 باستدعاءات vue-i18n الخاصة بها لكنها تخدمها من خلال محول التوافق @intlayer/vue-i18n. JavaScript لكل صفحة، حجم وقت التشغيل، حجم المكون والتسرب المقاس على نفس كود Vite + Vue، بالإضافة إلى ما يحتفظ به المحول وما يتجاهله وما لا يمكنه استبداله.
+keywords:
+  - vue-i18n
+  - "@intlayer/vue-i18n"
+  - Intlayer
+  - محول التوافق
+  - الهجرة
+  - الدولية
+  - i18n
+  - مقارنة الأداء
+  - حجم الحزمة
+  - مدونة
+  - Vue
+  - Nuxt
+  - Vite
+slugs:
+  - blog
+  - vue-i18n-vs-intlayer-vue-i18n
+author: aymericzip
+---
+
+# vue-i18n مقابل @intlayer/vue-i18n | نفس الواجهة البرمجية، حزمة مختلفة
+
+`@intlayer/vue-i18n` هو محول توافقي: يعرّض واجهة برمجية (API) من `vue-i18n` (`createI18n`، `useI18n`، `t()`، `d()`، `n()`، `$t`، `v-t`، `i18n.global.locale`...) ويقدمها من القواميس المترجمة بواسطة Intlayer. ملفات `.vue` الخاصة بك لا تتغير. ما يرتبط به `t("footer.github")` هو ما يتغير.
+
+تقيس هذه المقالة هذا التبديل على نفس تطبيق Vite + Vue 3، تم بناؤه مرة واحدة باستخدام `vue-i18n` ومرة أخرى باستخدام المحول. تأتي الأرقام من [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). لمقارنة `vue-i18n` و Intlayer كمكتبات، اقرأ [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) و[vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark). هذا يتعلق بما يغيره المحول عندما تحتفظ بمكوناتك كما هي.
+
+<TOC/>
+
+> **ملخص سريع**: على نفس تطبيق Vite + Vue 3، استبدال `vue-i18n` بـ `@intlayer/vue-i18n` أخذ JavaScript لكل صفحة من **134.9 KB إلى 47.0 KB** gzip (التطبيق بدون i18n يزن 41.3 KB)، وقت التشغيل من **24.3 KB إلى 7.9 KB**، متوسط المكون من **196 KB إلى 8.4 KB**، وتسرب السلاسل النصية للصفحات الأجنبية من **90% إلى 0%**، بدون تعديل أي ملف `.vue`. `createI18n({ messages })` يستمر في العمل كخيار بديل؛ أزل استيراد JSON للحصول على الأرقام أعلاه. كتل SFC `<i18n>` و `setLocaleMessage()` في وقت التشغيل هما الميزتان اللتان لا تنتقلان.
+
+## ما هو `@intlayer/vue-i18n`
+
+`vue-i18n` هي runtime. `createI18n({ messages: { en, fr, ... } })` تبني instance عام يحتفظ بكل رسالة من كل locale؛ `useI18n()` تربط كل component بها؛ `t("footer.github")` تمشي عبر الشجرة في وقت rendering. هذا التصميم هو ما يجعل SFC `<i18n>` blocks و `setLocaleMessage()` ممكنة، وهو أيضاً السبب في أن dependency graph لكل component يتضمن الشجرة بأكملها.
+
+`@intlayer/vue-i18n` تحافظ على API وتستبدل الشجرة:
+
+1. **Import aliasing.** `vueI18nVitePlugin()` من `@intlayer/vue-i18n/plugin` تغلف `vite-intlayer` وتضيف `resolve.alias` بحيث أن `vue-i18n` يتم حلها إلى `@intlayer/vue-i18n`. لم يتم إعادة تسمية أي import.
+2. **JSON كمصدر الحقيقة.** يقرأ plugin `syncJSON` ملف `locales/{locale}.json` الموجود لديك باستخدام `format: "vue-i18n"` (لذلك يتم تحليل استيفاء `{name}`، `{0}` list والجمع بين الأنابيب `"car | cars"` بشكل صحيح) ويكتب الترجمات مرة أخرى عندما يحدثها CLI أو CMS.
+3. **ربط موقع الاستدعاء.** تعيد مرحلة تحسين Intlayer كتابة مواقع استدعاء `useI18n()` بحيث يحصل المكون على القواميس الخاصة به مفاتيح الأسماء، في الإعدادات المحلية النشطة، كواردات يمكن للـ bundler تتبعها وتقسيمها.
+
+```vue fileName="src/components/Footer.vue"
+<!-- الكود الخاص بك، بدون تغيير -->
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <a href="https://github.com/intlayer-org/benchmark-bloom">{{
+    t("footer.github")
+  }}</a>
+</template>
+```
+
+```ts fileName="ما يصدره المترجم (مبسط)"
+import _dicHash_footer from "../.intlayer/dictionaries/footer.mjs";
+import { useDictionary as useI18n } from "@intlayer/vue-i18n";
+
+const { t } = useI18n(_dicHash_footer);
+```
+
+لم تعد المكون تصل إلى شجرة الرسائل العامة. تصل إلى `footer`. هذا هو السبب في انخفاض عمود حجم المكون أدناه من 196 كيلوبايت إلى 8 كيلوبايت.
+
+## ما يحافظ عليه المحول وما يتجاهله وما لا يستبدله
+
+| `vue-i18n` API                                                      | مع `@intlayer/vue-i18n`                                                                                                                    |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useI18n()` → `{ t, d, n, te, tm, rt, locale, availableLocales }`   | ✅ تم الاحتفاظ به. مفاتيح `t` مُكتوبة ضد قاموسك                                                                                            |
+| `t("key", { name })`, `t("key", [a, b])`, `t("key", count)`         | ✅ تم الاحتفاظ به. يتم حل `{name}`، `{0}` والجمع الفاصل بينها كما هو الحال من قبل                                                          |
+| `d(date, "long")`, `n(value, "currency")`                           | ✅ تم الاحتفاظ به. يتم احترام `datetimeFormats` / `numberFormats` من `createI18n()`، مدعومة بـ `Intl` الأصلي                               |
+| `i18n.global.locale.value = "fr"`                                   | ✅ تم الحفاظ عليه. `WritableComputedRef` مدعوم بـ Intlayer الخاص بالعميل؛ التفاعلية تتصرف كما هي                                           |
+| `$t`, `$tc`, `$te`, `$tm`, `$rt`, `$d`, `$n`, `$i18n` (Options API) | ✅ تم الحفاظ عليه. تم تسجيله على `app.config.globalProperties` بواسطة `app.use(i18n)`                                                      |
+| `v-t` directive                                                     | ✅ تم الحفاظ عليه                                                                                                                          |
+| `legacy: true`                                                      | ✅ مقبول                                                                                                                                   |
+| `createI18n({ messages })`                                          | ⚠️ يتم استخدام `messages` كـ **fallback في وقت التشغيل** مع تحذير في بيئة التطوير. قم بإزالة استيرادات JSON للحصول على مكاسب في حجم الحزمة |
+| `setLocaleMessage()`, `mergeLocaleMessage()`                        | ❌ تحذير وعدم القيام بأي شيء. يتم استبدال تحميل الرسائل في وقت التشغيل بقواميس build-time                                                  |
+| كتل `<i18n>` المخصصة في SFC                                         | ❌ لا يتم قراءتها. انقل تلك الرسائل إلى JSON اللغة (أو `.content.ts` بجانب المكون)                                                         |
+| `@nuxtjs/i18n`                                                      | ⚠️ محول منفصل، انظر [وثائق توافق Nuxt](https://intlayer.org/doc/compatibility/nuxtjs-i18n)                                                 |
+
+## المعايير
+
+### ما تم قياسه
+
+تبني مجموعة [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) **نفس تطبيق Vite + Vue 3** مع كل إعداد: **10 صفحات** (الرئيسية، حول، مدونة، الوظائف، اتصل، الأسئلة الشائعة، التسعير، المنتجات، الإعدادات، الفريق)، **10 لغات** (`en`، `fr`، `es`، `de`، `it`، `pt`، `zh`، `ja`، `ko`، `ru`)، مكونات متطابقة وأمتعة متطابقة. تُقاس الصفحات في `en` و `fr`.
+
+تم بناء كليهما في **الإعداد الثابت**، الذي تشحنه معظم مشاريع Vue: بالنسبة لـ `vue-i18n`، يتم استيراد JSON لكل لغة وتمريره إلى `createI18n({ messages })`؛ بالنسبة للمحول، نفس المكونات مع تغيير `vite.config.ts` و `intlayer.config.ts` وإزالة استيراد `messages`. يتم تضمين `vue-intlayer` الأصلي للمرجع.
+
+لكل بناء، تسجل المجموعة:
+
+- **حجم المكتبة**: حجم gzip (والمصغر) لمكون فارغ يستورد فقط مكتبة i18n.
+- **صفحة JS**: JavaScript بصيغة gzip يتم تنزيله لكل صفحة، بمتوسط على جميع الصفحات والإعدادات المحلية.
+- **تسرب الإعدادات المحلية %**: حصة السلاسل المترجمة في JavaScript المُنزَّل التي تنتمي إلى إعداد محلي لا يعرضه المستخدم.
+- **تسرب الصفحة %**: حصة السلاسل المترجمة في JavaScript المُنزَّل التي تنتمي إلى صفحة لا يوجد عليها المستخدم.
+- **متوسط المكون**: متوسط حجم gzip لكل مكون تم تجميعه بشكل منفصل.
+- **تفاعلية E2E**: وقت الساعة الحائط بين تحديد إعداد محلي جديد وتحديث `html[lang]` في DOM (Playwright، 5 تكرارات).
+- **تحميل الصفحة**: `PerformanceNavigationTiming.duration`.
+
+> الأرقام أدناه تأتي من التشغيل بتاريخ **2026-09-12** مع `vue-i18n` 11.4.0 و `@intlayer/vue-i18n` 9.5.1. تطبيق الاختبار صغير عن قصد (عدة عشرات من السلاسل النصية لكل locale)، لذا فإن نسب تسرب الـ locale تصف **نمطًا**: فهي تزداد مع محتواك بينما تبقى تكلفة التشغيل ثابتة.
+
+### النتائج على Vite + Vue 3
+
+| الإعداد                  | الإستراتيجية | حجم المكتبة (gz) | حجم المكتبة (min) | متوسط صفحة JS (gz) | تسرب Locale | تسرب الصفحة | متوسط المكون (gz) | استجابة E2E | تحميل الصفحة |
+| ------------------------ | ------------ | ---------------: | ----------------: | -----------------: | ----------: | ----------: | ----------------: | ----------: | -----------: |
+| **base** (no i18n)       | -            |           0.0 KB |            0.0 KB |            41.3 KB |        0.0% |           - |            1.1 KB |      1.8 ms |      10.8 ms |
+| `vue-i18n`               | static       |          24.3 KB |           83.2 KB |           134.9 KB |       50.0% |       90.0% |          196.0 KB |      2.8 ms |      13.6 ms |
+| **`@intlayer/vue-i18n`** | static       |       **7.9 KB** |       **23.2 KB** |        **47.0 KB** |   **15.0%** |    **0.0%** |        **8.4 KB** |  **1.5 ms** |   **9.3 ms** |
+| `vue-intlayer` (native)  | static       |           3.9 KB |           11.1 KB |            57.1 KB |       56.8% |        0.0% |            7.7 KB |      4.5 ms |      13.8 ms |
+| `vue-intlayer` (native)  | dynamic      |           3.9 KB |           11.1 KB |            59.8 KB |       50.0% |        0.0% |            6.5 KB |      4.0 ms |      15.8 ms |
+
+> عمود تسرب الصفحة في تطبيق الأساس مترك فارغاً: بدون مكتبة i18n، يلتقط بصمة الأصابع السلاسل المشفرة في الأجزاء المشتركة والرقم ليس ذا معنى.
+
+**كيفية قراءته**
+
+- **88 KB أقل لكل صفحة، نفس المكونات.** يأخذ `vue-i18n` تطبيق 41.3 KB إلى **134.9 KB**. يصل بناء المحول للمكونات نفسها إلى **47.0 KB**، 5.7 KB فوق تطبيق الأساس. معظم الفرق هو 74.9 KB من `src/locales` التي يسحبها `createI18n({ messages })` إلى كل صفحة والمحول لا يجمعها أبداً كتكتل.
+- **Runtime ينكمش 3 مرات.** مكون فارغ يستورد فقط `vue-i18n` يكلف **24.3 KB gzip / 83.2 KB minified**: `@intlify/core-base`، مترجم الرسائل والـ runtime. المحول يكلف **7.9 KB / 23.2 KB**، معظمها نواة Intlayer بالإضافة إلى سطح API `vue-i18n`.
+- **المكونات: أصغر 23 مرة.** مكون `useI18n()` مترجم بشكل معزول يبلغ متوسطه **196 KB**، لأن `t` مرتبط بالمثيل الذي يحتفظ بكل رسالة من كل locale. مع المحول، نفس المكون يبلغ متوسطه **8.4 KB**: فهو يصل إلى قاموسه الخاص.
+- **تسرب البيانات.** يشحن `vue-i18n` كل locale وسلاسل كل صفحة على كل صفحة: تسرب locale بنسبة 50% (على locale المرقمة الاثنين؛ مع عشرة locales مجمعة فإن الهدر الفعلي أعلى)، تسرب صفحة بنسبة 90%. يقلل المحول تسرب الصفحة إلى **0%** لأن كل مكون يستورد فقط قاموسه الخاص. يجلس تسرب Locale عند 15% في هذا التشغيل `static`؛ `importMode: 'dynamic'` هو الإعداد الذي يزيله، وكان هذا التكوين ليس جزءاً من تشغيل Vue هذا.
+- **التفاعلية وتحميل الصفحة.** تبديل Locale رخيص لكليهما (1.5-2.8 ms)؛ نظام التفاعلية في Vue يجعل الأمر كذلك بمجرد أن تكون الرسائل في الذاكرة. يذهب تحميل الصفحة من 13.6 ms إلى **9.3 ms**، متماشياً مع 88 KB أقل من JavaScript للتحليل.
+- **حول الصفوف الأصلية.** `vue-intlayer` في هذا التشغيل جمعت كل اللغة في وضع `static` وحققت 57.1 كيلوبايت مع وقت تشغيل 3.9 كيلوبايت؛ قاموس المحول المتزامن حمل سلاسل لغات أجنبية أقل، وبالتالي الرقم الأقل لكل صفحة. وقت التشغيل الأصلي يبقى الأخف من بين الثلاثة، وموديل `.content.ts` الخاص به هو حيث تجد كتل SFC `<i18n>` معادلتها.
+
+## لماذا تتحرك الأرقام
+
+لم يتغير شيء في `src/components/`، لذا الفوائد تأتي من ما ترتبط به `useI18n`.
+
+**مع `vue-i18n`**, الربط هو المثيل العام. `createI18n({ messages: { en, fr, ... } })` هو استيراد واحد يحتوي على كل شيء؛ كل مكون يستدعي `useI18n()` يمكنه الوصول إلى كل شيء، لذلك لا يمكن للـ bundler أن ينقسم دون المثيل. التحسين يعني _أنت_ تقسم `en.json` حسب المسار، تستدعي `setLocaleMessage()` في حارس التوجيه، وتحافظ على خريطة المسار إلى الملف صحيحة عند تحرك المكونات.
+
+```bash
+.
+├── locales
+│   ├── en.json                    # سلاسل كل صفحة
+│   └── fr.json
+└── src
+    ├── i18n.ts                    # createI18n({ messages: { en, fr, ... } })
+    ├── main.ts                    # app.use(i18n)
+    └── components
+        └── Footer.vue             # useI18n(); t("footer.github")
+```
+
+**مع `@intlayer/vue-i18n`**، الربط هو القاموس. `syncJSON` يحول كل مفتاح من المستوى الأعلى في `en.json` إلى قاموس؛ تمرير التحسين يسلم المكون الذي يسمي مفاتيحه، حيث يتتبع bundler الواردات ويقسمها حسب الصفحة.
+
+```bash
+.
+├── intlayer.config.ts             # syncJSON({ format: "vue-i18n", source: ... })
+├── locales
+│   ├── en.json                    # لم يتغير، لا يزال مصدر الحقيقة
+│   └── fr.json
+├── .intlayer/                     # تم إنشاؤه: قاموس واحد لكل مفتاح من المستوى الأعلى، لكل locale
+└── src
+    ├── i18n.ts                    # createI18n({})   ← تم إزالة استيراد messages
+    ├── main.ts                    # app.use(i18n)    ← لم يتغير
+    └── components
+        └── Footer.vue             # useI18n(); t("footer.github")  ← لم يتغير
+```
+
+سطر `messages` المستورد في `i18n.ts` هو السطر الوحيد الذي يجب حذفه. هذا هو 88 كيلوبايت.
+
+## الهجرة في ثلاث خطوات
+
+<Steps>
+<Step number={1} title="التثبيت">
+
+```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
+```
+
+يكتشف الأمر `vue-i18n`، ويثبت `intlayer`، و`vue-intlayer`، و`@intlayer/vue-i18n` و`@intlayer/sync-json-plugin`، ويملأ `intlayer.config.ts` مسبقاً. احتفظ بـ `vue-i18n` مثبتاً: فهو peer dependency ويوفر الأنواع.
+
+</Step>
+<Step number={2} title="وجّه Intlayer إلى ملفات اللغة الخاصة بك">
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    // "static" تجميع كل locale؛ "dynamic" تحميل النشط عند الطلب
+    importMode: "dynamic",
+    format: "vue-i18n",
+  },
+  plugins: [
+    syncJSON({
+      // لهجة vue-i18n: {name}, {0}, "car | cars"
+      format: "vue-i18n",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      location: "locales",
+    }),
+  ],
+};
+
+export default config;
+```
+
+يبقى `locales/{locale}.json` في مكانه. كل مفتاح على المستوى الأعلى (`footer`, `hero`...) يصبح قاموس.
+<Step number={3} title="أضف الـ plugin وحذف استيراد الرسائل">
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { vueI18nVitePlugin } from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+```ts fileName="src/i18n.ts"
+import { createI18n } from "vue-i18n";
+
+// قبل: createI18n({ locale: "en", messages: { en, fr, es } })
+export const i18n = createI18n({ locale: "en" });
+```
+
+`vueI18nVitePlugin()` يغلف `vite-intlayer` (مراقبة المحتوى، تجميع القاموس، عملية التحسين) ويقوم بإنشاء alias لـ `vue-i18n` إلى الـ adapter. إزالة استيراد `messages` هو ما يقلل 88 KB؛ تركه في الكود يبقي التطبيق يعمل لكنه يشحن الاثنين معاً.
+
+</Step>
+</Steps>
+
+### ما يمكنك حذفه لاحقًا
+
+| الملف / النمط                                          | السبب                                                                 |
+| ------------------------------------------------------ | --------------------------------------------------------------------- |
+| `import en from "./locales/en.json"` والملفات المشابهة | يُستخدم فقط كآلية احتياطية من قِبل adapter. هنا كان موقع 88 كيلوبايت  |
+| `setLocaleMessage()` في route guards                   | عملية بلا تأثير. تحميل لكل مسار هو وظيفة المترجم الآن                 |
+| `@intlify/unplugin-vue-i18n`                           | غير مطلوب: فهو يقوم بتجميع الرسائل وكتل SFC التي لا يقرأها adapter    |
+| كتل `<i18n>` في المكونات أحادية الملف (SFC)            | لا تُقرأ؛ انقلها إلى ملفات JSON المحلية أو إلى `.content.ts` لكل مكون |
+
+### ما الذي تكسبه بعيداً عن البايتات
+
+- **مفاتيح مكتوبة.** `t("footer.github")` مكتوب مقابل قاموس `footer` المترجم؛ المسار الخاطئ هو خطأ في TypeScript بدلاً من عرض المفتاح كنص.
+- **`npx intlayer test`** يفشل في CI عند وجود مفتاح مفقود في أي محلية. **`npx intlayer fill`** يترجم الناقصة باستخدام مفتاح مزود خاص بك (OpenAI أو Anthropic أو Mistral أو Gemini...) ويكتبها مرة أخرى في `locales/{locale}.json`.
+- **محرر مرئي و CMS** يعملان على نفس JSON، لذا يقوم المطورون بعدم التحرير من خلال واجهة المستخدم وتحديث الملفات.
+- **الانتقال التدريجي إلى `.content.ts`.** يمكن لأي مكون الانتقال من `useI18n()` إلى `useIntlayer("footer")` مع ملف محتوى مرافق. قواميس JSON و`.content.ts` موجودة وتندمج معاً.
+
+## الحدود التي يجب معرفتها قبل البدء
+
+- **كتل SFC `<i18n>` لا تُقرأ.** إذا كانت رسائلك موجودة داخل المكونات، فيجب نقلها إلى ملفات الإعدادات الإقليمية (أو إلى `.content.ts`، وهي نفس الفكرة مع الأنواع).
+- **تحميل الرسائل في وقت التشغيل قد اختفى.** `setLocaleMessage()` و `mergeLocaleMessage()` تحذر وتعود. الترجمات المجلوبة من نظام إدارة المحتوى في وقت التشغيل تحتاج إلى نظام إدارة محتوى Intlayer، أو أوامر `intlayer pull` / `push`.
+- **`messages` هو بديل، وليس مجاني.** الاحتفاظ باستيرادات JSON في `createI18n()` يحتفظ بـ 75 KB في الحزمة. احذفها بمجرد نجاح `intlayer test`.
+- **المحول ليس runtime الأصلي.** 7.9 KB مقابل 3.9 KB لـ `vue-intlayer`. بمجرد انتقال كل component إلى `useIntlayer`، يمكنك حذفه.
+
+## متى تستخدم أي منها؟
+
+- **ابق على `vue-i18n`** إذا كان تطبيقك يعتمد على كتل SFC `<i18n>`، على تدفقات runtime `setLocaleMessage()`، أو إذا لم يكن 90 KB لكل صفحة مصدر قلق لجمهورك.
+- **استخدم `@intlayer/vue-i18n`** إذا كنت على `vue-i18n` وتريد توفير 88 KB، و23x أصغر components، 0% page leakage، typed keys وفحوصات CI دون تعديل ملف `.vue`. هذه هي نقطة الدخول لـ codebase `vue-i18n` موجود.
+- **اذهب للنسخة الأصلية (`vue-intlayer`)** للمشاريع الجديدة، أو بمجرد انتهاء المحول من عمله. لديها أخف runtime (3.9 KB) والنموذج `.content.ts` لكل component الذي يحل محل كتل `<i18n>` بمحتوى مكتوب (typed).
+
+## المقارنات ذات الصلة
+
+- [vue-i18n مقابل Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (الميزات وتجربة المطور)
+- [معيار vue-i18n مقابل Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (المكتبات، نفس المعيار)
+- [next-intl مقابل @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (نفس سلسلة المحولات)
+- [i18next مقابل @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (نفس سلسلة المحولات)
+- [Lingui مقابل @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (نفس سلسلة المحولات)
+- [دليل الترحيل: من vue-i18n إلى Intlayer](https://intlayer.org/doc/migration/vue-i18n)
+- [مرجع محول التوافق: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+
+## الخلاصة
+
+يغير `@intlayer/vue-i18n` ما يرتبط به `useI18n()`: من مثيل عام يحمل كل رسالة من كل locale إلى قاموس مُجمّع لتلك المكون. في نفس تطبيق Vite + Vue 3 الذي هو **88 KB أقل لكل صفحة**، وقت تشغيل **أصغر 3 مرات**، مكونات **أصغر 23 مرة** و**تسرب صفحة 0%**، لملف إعدادات وسطر plugin وواحد استيراد محذوف. كتل SFC `<i18n>` وتحميل الرسائل في وقت التشغيل هما الشيئان اللذان لا يحملهما، وبقي runtime `vue-intlayer` الأصلي نصف حجمه.
+
+جميع البيانات الأولية وتطبيقات الاختبار والسكريبتات موجودة في [مستودع Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). قم بتشغيلها بنفسك.
+
+راجع وثيقة ['Why Intlayer?'](https://intlayer.org/doc/why) للحصول على مزيد من التفاصيل.

package/blog/de/i18next_vs_intlayer-i18next.md

@@ -0,0 +1,327 @@
+---
+createdAt: 2026-09-13
+updatedAt: 2026-09-13
+title: "i18next vs @intlayer/i18next: Gleiche API, anderes Bundle"
+description: Was sich ändert, wenn eine React- oder Next.js-App ihre i18next-, react-i18next- und next-i18next-Aufrufe beibehält, diese jedoch über die @intlayer/i18next-Adapter bereitstellt. JavaScript pro Seite, Komponentengröße, Content-Leakage und Hydration gemessen am gleichen Code, plus was die Adapter behalten, ignorieren und nicht ersetzen können.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - "@intlayer/i18next"
+  - "@intlayer/react-i18next"
+  - "@intlayer/next-i18next"
+  - Intlayer
+  - Kompatibilitätsadapter
+  - Migration
+  - Internationalisierung
+  - i18n
+  - Benchmark
+  - Bundle-Größe
+  - Blog
+  - Next.js
+  - React
+slugs:
+  - blog
+  - i18next-vs-intlayer-i18next
+author: aymericzip
+---
+
+# i18next VS @intlayer/i18next | Gleiche API, anderes Bundle
+
+`@intlayer/i18next`, `@intlayer/react-i18next` und `@intlayer/next-i18next` sind Kompatibilitätsadapter. Sie stellen die `i18next`-API bereit, die Ihr Code bereits verwendet (`useTranslation`, `t()`, `<Trans>`, `i18n.changeLanguage()`, `getFixedT`, `serverSideTranslations`...), und bedienen sie aus von Intlayer kompilierten Wörterbüchern. Die Komponenten ändern sich nicht. Die Runtime darunter jedoch schon.
+
+Dieser Artikel misst diesen Austausch an derselben Next.js-Anwendung, die einmal mit `next-i18next` und einmal mit `@intlayer/next-i18next` gebaut wurde. Die Zahlen stammen aus [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Für einen Vergleich von `i18next` und Intlayer als eigenständige Bibliotheken lesen Sie [i18next vs Intlayer](https://intlayer.org/de/blog/i18next-vs-intlayer). Hier geht es darum, was der Adapter verändert, wenn Sie Ihren bestehenden Code unverändert beibehalten.
+
+<TOC/>
+
+> **tl;dr**: In derselben Next.js-App reduzierte der Wechsel von `next-i18next` zu `@intlayer/next-i18next` das JavaScript pro Seite von **218.5 KB auf 150.7 KB** gzip (Basis-Setup) und unterbot selbst das vollständig optimierte `next-i18next`-Setup (163.4 KB) um **12.7 KB**. Die durchschnittliche Komponentengröße sank von **78.5 KB auf 9.7 KB**, das String-Leakage fremder Seiten von **~90% auf 0%**, die Hydration-Dauer von **15.6 ms auf 11.3 ms** und die Runtime von **19.7 KB auf 9.4 KB**. Keine einzige Komponente musste angepasst werden; lediglich eine Provider-Datei wurde geändert. `i18next`-Plugins (Backends, Spracherkenner) werden akzeptiert, bewirken aber nichts: Zur Laufzeit muss nichts mehr geladen oder erkannt werden.
+
+## Was `@intlayer/i18next` ist
+
+`i18next` ist eine Runtime. `i18n.init({ resources })` oder ein Backend-Plugin lädt `locales/{lng}/{ns}.json` in eine globale Instanz; `useTranslation("about")` abonniert die Komponente darauf; `t("title")` schlägt den Schlüssel zur Renderzeit nach. Namespaces, Lazy Loading, seitenbasierte Namespace-Listen und Typsicherheit müssen von Ihnen konfiguriert und gepflegt werden.
+
+Die Adapter behalten die API bei und ersetzen die globale Instanz:
+
+1. **Import-Aliasing.** `createNextI18nPlugin()` aus `@intlayer/next-i18next/plugin` (oder `withI18next`) umschließt `withIntlayer` und richtet Webpack- / Turbopack-Aliase ein, sodass `next-i18next`, `react-i18next` und `i18next` auf ihre `@intlayer/*`-Gegenstücke aufgelöst werden. Unter Vite übernimmt `reactI18nextVitePlugin()` aus `@intlayer/react-i18next/plugin` die gleiche Aufgabe. Kein einziger Import muss umbenannt werden.
+2. **JSON als Source of Truth.** Das `syncJSON`-Plugin liest Ihre bestehenden `locales/{lng}/{ns}.json`-Dateien mit `format: "i18next"` (sodass `{{name}}`, `$t()`-Verschachtelungen, `_one` / `_other` und Kontext-Suffixe korrekt geparst werden) und schreibt Übersetzungen zurück, sobald die CLI oder das CMS sie aktualisiert.
+3. **Bindung am Aufrufpunkt.** Der Optimierungsschritt von Intlayer schreibt `useTranslation("about")` in einen Aufruf um, der das Wörterbuch `about` direkt in der aktiven Locale empfängt. Die Komponente greift nicht mehr auf den globalen Store zu.
+
+```tsx fileName="components/About.tsx"
+// Ihr Code, unverändert
+import { useTranslation } from "react-i18next";
+
+const About = () => {
+  const { t } = useTranslation("about");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+```tsx fileName="Was der Compiler ausgibt (vereinfacht)"
+import _dicHash_about from "../.intlayer/dictionaries/about.mjs";
+import { useDictionary as useTranslation } from "@intlayer/react-i18next";
+
+const About = () => {
+  const { t } = useTranslation(_dicHash_about);
+  return <h1>{t("title")}</h1>;
+};
+```
+
+Dieser Umschreibprozess sorgt für die drastische Verkleinerung der Komponenten und den Wegfall des Seiten-Leakages in den folgenden Messungen.
+
+## Was die Adapter beibehalten, ignorieren und nicht ersetzen
+
+| `i18next`-API                                                                   | Mit `@intlayer/*`                                                                                                 |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `useTranslation("ns")`, `useTranslation("ns", { keyPrefix })`                   | ✅ Beibehalten. Zur Build-Zeit an das `ns`-Wörterbuch gebunden; typisiert gegen Ihre Inhalte                      |
+| `t("key", { name })`, `{{interpolation}}`, `$t(key)`-Verschachtelung            | ✅ Beibehalten                                                                                                    |
+| Pluralformen `key_one` / `key_other`, Kontext `key_male`, `returnObjects`       | ✅ Beibehalten. Plurale werden über `Intl.PluralRules` ausgewertet                                                |
+| `<Trans>` mit `components`, nummerierten Tags `<1>...</1>`, `values`            | ✅ Beibehalten                                                                                                    |
+| `withTranslation`, `Translation`, `I18nContext`                                 | ✅ Beibehalten                                                                                                    |
+| `i18n.changeLanguage()`, `i18n.language`, `i18n.dir()`, `on("languageChanged")` | ✅ Beibehalten. `changeLanguage` steuert die Locale von Intlayer                                                  |
+| `getFixedT(lng, ns, keyPrefix)`, `i18n.exists()`, `hasLoadedNamespace()`        | ✅ Beibehalten                                                                                                    |
+| `i18n.use(Backend).use(LanguageDetector).init({...})`                           | ⚠️ `use()` ruft `init` des Plugins auf und beendet; Backends und Detectors müssen nichts laden oder ermitteln     |
+| `init({ resources })`, `addResourceBundle()`                                    | ⚠️ `resources` wird mit einer Warnung **ignoriert**; entfernen Sie JSON-Imports für optimale Bundle-Größen        |
+| `I18nextProvider i18n={i18n}`                                                   | ⚠️ Rendert einen `IntlayerProvider`; die `i18n`-Prop wird ignoriert. Im App Router Locale übergeben (siehe unten) |
+| `serverSideTranslations(locale, ["common"])` (next-i18next)                     | ⚠️ Gibt die erwartete Struktur zurück und lädt nichts. Unschädlich beizubehalten, sicher zu löschen               |
+| `appWithTranslation(App)` (next-i18next)                                        | ✅ Beibehalten                                                                                                    |
+| `next-i18next.config.js`                                                        | ⚠️ Wird nicht gelesen. Locales stammen aus `intlayer.config.ts`                                                   |
+| Einfaches `useTranslation()` ohne Namespace                                     | ✅ Funktioniert gegen das `translation`-Gesamtwörterbuch der Datei (`splitKeys: false`)                           |
+
+## Der Benchmark
+
+### Was gemessen wurde
+
+Die Testsuite [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) erstellt **dieselbe Anwendung** in jedem Setup: **10 Seiten** (Home, About, Blog, Careers, Contact, FAQ, Pricing, Products, Settings, Team), **10 Locales** (`en`, `fr`, `es`, `de`, `it`, `pt`, `zh`, `ja`, `ko`, `ru`), identische Komponenten und identischer Inhalt. Die Seiten werden in `en` und `fr` gemessen.
+
+`next-i18next` wurde in vier Ladestrategien getestet: vom Import aller Locale-JSONs in `resources` (`static`) bis hin zu einem Namespace pro Route, der über ein Backend nachgeladen wird (`scoped-dynamic`). Der Adapter lief auf **denselben Komponenten wie das Basis-Setup**, wobei lediglich `next.config.ts`, `intlayer.config.ts` und die Provider-Datei angepasst wurden. Er benötigt keine manuell "gescopte" Variante: Der Compiler grenzt den Inhalt automatisch pro Komponente ab.
+
+Für jeden Build erfasst die Suite:
+
+- **Lib-Größe**: gzip-Größe einer leeren Komponente, die lediglich die i18n-Bibliothek importiert.
+- **Seiten-JS**: Durchschnittliches gzip-JavaScript, das pro Seite über alle Seiten und Locales heruntergeladen wird.
+- **Locale-Leakage %**: Anteil übersetzter Strings im heruntergeladenen JS, der zu einer Sprache gehört, die der Nutzer **nicht** betrachtet.
+- **Seiten-Leakage %**: Anteil übersetzter Strings im heruntergeladenen JS, der zu einer Seite gehört, auf der sich der Nutzer **nicht** befindet.
+- **Komponenten-Durchschnitt**: Durchschnittliche gzip-Größe jeder isoliert kompilierten Komponente.
+- **E2E-Reaktivität**: Gemessene Zeitspanne zwischen der Sprachauswahl und der Aktualisierung von `html[lang]` im DOM (Playwright, 5 Durchläufe).
+- **Hydration**: Dauer der React-Hydration-Phase.
+
+> Die folgenden Zahlen stammen aus dem Durchlauf vom **12.09.2026** mit `next-i18next` 16.3.0 (`react-i18next` 17.0.13, `i18next` 26.4.2) und `@intlayer/next-i18next` 9.5.1. Die Testanwendung ist bewusst kompakt gehalten (wenige Dutzend Zeichenketten pro Sprache), sodass die Leakage-Prozentwerte ein **Muster** abbilden: Sie steigen mit wachsendem Content, während die Runtime-Kosten konstant bleiben.
+
+### Ergebnisse auf Next.js
+
+| Setup                        | Strategie      | Lib-Größe (gz) | Seiten-JS Ø (gz) | Locale-Leakage | Seiten-Leakage | Komp Ø (gz) | E2E-Reaktivität |   Hydration |
+| ---------------------------- | -------------- | -------------: | ---------------: | -------------: | -------------: | ----------: | --------------: | ----------: |
+| **base** (ohne i18n)         | -              |         0.0 KB |         141.0 KB |           0.0% |           0.0% |      0.9 KB |         13.4 ms |     11.8 ms |
+| `next-i18next`               | static         |        19.7 KB |         218.5 KB |           0.0% |          89.8% |     78.5 KB |         16.4 ms |     15.6 ms |
+| `next-i18next`               | dynamic        |        19.7 KB |         169.5 KB |          50.0% |          89.8% |     26.1 KB |         15.4 ms |     27.7 ms |
+| `next-i18next`               | scoped-static  |        19.7 KB |         220.1 KB |           0.0% |          89.8% |     78.9 KB |         16.4 ms |     14.7 ms |
+| `next-i18next`               | scoped-dynamic |        19.7 KB |         163.4 KB |           0.0% |           0.0% |     27.1 KB |         15.9 ms |     15.1 ms |
+| **`@intlayer/next-i18next`** | static         |     **9.4 KB** |     **150.7 KB** |       **0.0%** |       **0.0%** |  **9.7 KB** |     **10.7 ms** | **11.3 ms** |
+| **`@intlayer/next-i18next`** | dynamic        |     **9.4 KB** |     **150.7 KB** |       **0.0%** |       **0.0%** |  **9.7 KB** |     **11.9 ms** | **10.6 ms** |
+| `next-intlayer` (nativ)      | static         |         5.5 KB |         141.3 KB |           0.0% |           0.0% |      8.5 KB |         15.5 ms |     16.9 ms |
+| `next-intlayer` (nativ)      | dynamic        |         5.5 KB |         141.3 KB |           0.0% |           0.0% |      6.9 KB |         15.3 ms |     15.9 ms |
+
+**Einordnung der Ergebnisse**
+
+- **68 KB weniger pro Seite gegenüber dem Basis-Setup.** `resources: { en, fr, ... }` liefert jede Sprache und jeden Namespace auf jeder Seite aus: **218.5 KB**. Der Adapter-Build derselben Komponenten landet bei **150.7 KB**. Er unterbietet auch die beste Konfiguration von `next-i18next` (163.4 KB, ein Namespace pro Route, nachgeladen) um 12.7 KB, da die `i18next`-Runtime allein 19.7 KB gegenüber 9.4 KB wiegt.
+- **Leakage sinkt auf 0%, ohne Komponenten zu verändern.** Jedes `next-i18next`-Setup außer der vollkommen isolierten Variante liefert ~90% fremde Seiten-Strings aus. Das `dynamic`-Setup schneidet schlechter ab als erwartet: Es behält das Seiten-Leakage bei und erzeugt zusätzlich **50% Locale-Leakage**, da das Backend pro Sprache stets den gesamten `translation`-Namespace abruft. Der Adapter erreicht 0% / 0% direkt auf dem Ursprungscode.
+- **Komponenten: 8x kleiner.** Eine isoliert kompilierte `useTranslation()`-Komponente wiegt durchschnittlich **78.5 KB** mit eingebetteten `resources` und **26-27 KB** mit Backend, da `t` an den globalen Store gebunden ist. Mit dem Adapter sind es durchschnittlich **9.7 KB**.
+- **Schnellere Hydration und Sprachwechsel.** Die Hydration sinkt von 15.6 ms auf **11.3 ms** (und von 27.7 ms im `dynamic`-Setup, wo der Backend-Aufruf auf dem kritischen Pfad liegt). Der Sprachwechsel beschleunigt sich von 15-16 ms auf **11-12 ms**.
+- **Der Adapter ist nicht die native Runtime.** `next-intlayer` kommt auf **141.3 KB**, lediglich +0.3 KB über der Basis-App. Der Adapter bringt die API-Oberfläche von `i18next` (Interpolation, Plural- und Kontext-Suffixe, `<Trans>`-Parsing) auf dem Core von Intlayer mit: 9.4 KB und +9.4 KB pro Seite über nativ. Er ist die Brücke, nicht das Endziel.
+
+> Der `react-i18next`-Adapter unter Vite / TanStack Start war nicht Teil dieser Messreihe. Die Werte für `react-i18next` auf TanStack Start finden sich in [i18next vs Intlayer](https://intlayer.org/de/blog/i18next-vs-intlayer): 127-184 KB pro Seite und 123-185 ms beim Sprachwechsel bei nachgeladenem Backend.
+
+## Warum sich die Zahlen verändern
+
+Am Ordner `components/` wurde nichts geändert; die Einsparungen resultieren daraus, woran `useTranslation` gebunden ist.
+
+**Bei `i18next`** erfolgt die Bindung an die globale Instanz. Alles, was hineingeladen wurde (alle Sprachen bei `static`, der gesamte Namespace der aktiven Sprache bei `dynamic`), ist für jede Komponente erreichbar, die `useTranslation()` aufruft. Der Bundler kann nicht feiner trennen als der Instanzinhalt, und die Runtime kann nicht wissen, welche Schlüssel eine Komponente beim Rendern anfordern wird.
+
+```bash
+.
+├── next-i18next.config.js
+├── public/locales
+│   ├── en/translation.json           # Strings aller Seiten
+│   └── fr/translation.json
+├── i18n/i18n.ts                      # i18n.use(initReactI18next).init({ resources })
+└── components
+    ├── AppProviders.tsx              # <I18nextProvider i18n={i18n}>
+    └── About.tsx                     # useTranslation(); t("about.title")
+```
+
+**Bei `@intlayer/next-i18next`** bindet der Aufruf direkt an das Wörterbuch. `syncJSON` wandelt jede Namespace-Datei in ein Wörterbuch um; der Optimierungsschritt übergibt der Komponente exakt das benötigte Wörterbuch als Import, den der Bundler pro Seite und pro Sprache isolieren und aufteilen kann.
+
+```bash
+.
+├── intlayer.config.ts                # syncJSON({ format: "i18next", source: ... })
+├── public/locales
+│   ├── en/translation.json           # unverändert, weiterhin die Source of Truth
+│   └── fr/translation.json
+├── .intlayer/                        # generiert: ein Wörterbuch pro Namespace, pro Sprache
+└── components
+    ├── AppProviders.tsx              # <IntlayerClientProvider locale={locale}>
+    └── About.tsx                     # useTranslation(); t("about.title")  ← unverändert
+```
+
+`i18n/i18n.ts` und dessen `resources`-Import werden zu totem Code. Genau daraus resultieren die 68 KB Einsparung.
+
+## Migration in drei Schritten
+
+<Steps>
+<Step number={1} title="Installation">
+
+```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
+```
+
+Der Befehl erkennt `i18next` / `react-i18next` / `next-i18next`, installiert `intlayer`, das Framework-Paket (`next-intlayer` oder `react-intlayer`), den passenden `@intlayer/*`-Adapter sowie `@intlayer/sync-json-plugin` und füllt `intlayer.config.ts` vor. Behalten Sie die bisherigen Pakete installiert: Sie fungieren als Peer-Dependencies und liefern die TypeScript-Definitionen.
+
+</Step>
+<Step number={2} title="Intlayer auf Ihre Sprachdateien ausrichten">
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+    format: "i18next",
+  },
+  plugins: [
+    syncJSON({
+      // i18next-Dialekt: {{name}}, $t(key), key_one / key_other, key_male
+      format: "i18next",
+      // Eine Datei pro Namespace: `useTranslation("about")` → about.json
+      source: ({ locale, key }) => `./public/locales/${locale}/${key}.json`,
+      location: "public/locales",
+    }),
+  ],
+};
+
+export default config;
+```
+
+Wenn Sie eine einzige `translation.json` pro Sprache verwenden (der Standard-Namespace von i18next), setzen Sie `splitKeys: false`, damit die gesamte Datei ein einziges Wörterbuch bleibt und einfache Aufrufe von `useTranslation()` weiterhin funktionieren.
+
+</Step>
+<Step number={3} title="Plugin hinzufügen">
+
+<Tabs>
+<Tab label="Next.js">
+
+```ts fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { withI18next } from "@intlayer/next-i18next/plugin";
+
+const nextConfig: NextConfig = {};
+
+export default withI18next(nextConfig);
+```
+
+Im App Router erhalten Client-Komponenten ihre Sprache über das `[locale]`-Segment. Der `I18nextProvider` des Adapters nimmt keine Sprache entgegen, daher ersetzen Sie ihn einmalig in Ihrer Provider-Datei:
+
+```tsx fileName="components/AppProviders.tsx"
+"use client";
+
+import { IntlayerClientProvider } from "next-intlayer";
+import type { LocalesValues } from "intlayer";
+
+export const AppProviders = ({
+  locale,
+  children,
+}: {
+  locale: LocalesValues;
+  children: React.ReactNode;
+}) => (
+  <IntlayerClientProvider locale={locale}>{children}</IntlayerClientProvider>
+);
+```
+
+Alle darunter liegenden Komponenten rufen weiterhin wie gewohnt `useTranslation()` auf.
+
+</Tab>
+<Tab label="Vite / TanStack Start">
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+`reactI18nextVitePlugin()` umschließt `vite-intlayer` und richtet Aliase für `react-i18next` und `i18next` ein. Für ein Projekt ohne React aliast `i18nextVitePlugin()` aus `@intlayer/i18next/plugin` das Basispaket `i18next`.
+
+</Tab>
+</Tabs>
+
+</Step>
+</Steps>
+
+### Was Sie anschließend entfernen können
+
+| Datei / Muster                                         | Grund                                                                               |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `resources: { en, fr, ... }` und die JSON-Imports      | Werden vom Adapter ignoriert. Hier lagen die 68 KB                                  |
+| `i18next-http-backend`, `i18next-resources-to-backend` | Zur Laufzeit muss nichts mehr abgerufen werden                                      |
+| `i18next-browser-languagedetector`                     | Die Spracherkennung übernimmt das Routing von Intlayer (URL-Präfix, Cookie, Header) |
+| `serverSideTranslations()` in `getStaticProps`         | Liefert eine leere Struktur; harmlos, aber überflüssig                              |
+| `next-i18next.config.js`                               | Wird nicht gelesen. Sprachen liegen in `intlayer.config.ts`                         |
+| Listen mit `ns: [...]` pro Seite                       | Der Compiler wählt Namespaces komponentenweise aus                                  |
+
+### Was Sie über Dateigrößen hinaus gewinnen
+
+- **Typisierte Schlüssel.** `useTranslation("about")` ist gegen das kompilierte `about`-Wörterbuch typisiert; `t("does.not.exist")` führt zu einem TypeScript-Fehler statt zu einem zurückgegebenen Key-String.
+- **`npx intlayer test`** lässt die CI bei fehlenden Schlüsseln in beliebigen Sprachen fehlschlagen. **`npx intlayer fill`** übersetzt fehlende Einträge mit Ihrem eigenen Provider-Schlüssel (OpenAI, Anthropic, Mistral, Gemini...) und schreibt sie in `locales/{lng}/{ns}.json` zurück.
+- **Visueller Editor und CMS** arbeiten auf demselben JSON, sodass Übersetzer Inhalte per UI bearbeiten können und Dateien synchronisiert werden.
+- **Schrittweiser Wechsel zu `.content.ts`.** Jede Komponente kann unabhängig von `useTranslation("about")` auf `useIntlayer("about")` mit einer zugehörigen Inhaltsdatei umgestellt werden. JSON und `.content.ts`-Dateien koexistieren reibungslos.
+
+## Grenzen, die Sie vorab kennen sollten
+
+- **Backends und Detektoren sind inaktiv.** `i18n.use(HttpBackend)` ruft das `init` des Plugins auf und nichts weiter. Wenn Ihre App darauf angewiesen war, Übersetzungen zur Laufzeit von einem CMS abzurufen, entfällt dieser Pfad; nutzen Sie stattdessen das Intlayer-CMS oder die Befehle `intlayer pull` / `push`.
+- **`resources` wird ignoriert, nicht zusammengeführt.** Im Gegensatz zu manchen anderen Adaptern nutzt `@intlayer/i18next` eingebettete `resources` nicht als Fallback. Jeder Schlüssel muss in den synchronisierten Wörterbüchern vorhanden sein, was `intlayer test` absichert.
+- **App Router erfordert die Provider-Änderung.** Eine Datei, oben dargestellt. Pages Router mit `appWithTranslation` benötigt keinerlei Änderungen.
+- **`next-i18next.config.js` wird ignoriert.** `localePath`, `fallbackLng`, `reloadOnPrerender` und Verwandte haben keine Wirkung; Sprachen und Fallbacks werden in `intlayer.config.ts` definiert.
+- **Der Adapter ist nicht kostenlos.** 9.4 KB Runtime und +9.4 KB pro Seite gegenüber `next-intlayer`. Sobald alle Komponenten auf `useIntlayer` umgestellt sind, kann er entfernt werden.
+
+## Wann welche Lösung wählen?
+
+- **Bleiben Sie bei `i18next`**, wenn Ihre Anwendung zwingend auf Runtime-Backends (zur Anfragezeit aus einem CMS geladene Übersetzungen), das Plugin-Ökosystem oder ein Nicht-React-Target angewiesen ist, das die Adapter nicht abdecken.
+- **Nutzen Sie `@intlayer/*`**, wenn Sie `react-i18next` / `next-i18next` einsetzen und 68 KB sparen, 8x kleinere Komponenten, 0% Leakage, typisierte Schlüssel und CI-Prüfungen ohne Code-Rewrite erhalten möchten. Dies ist der beste Einstieg für bestehende `i18next`-Codebasen.
+- **Wählen Sie nativ (`next-intlayer` / `react-intlayer`)** für Neuprojekte oder sobald der Adapter seinen Dienst getan hat. Es ist die schlankste Variante (5.5 KB, +0.3 KB pro Seite) und schaltet synchrone Server-Komponenten sowie komponentenbasierte `.content.ts`-Dateien frei.
+
+## Verwandte Vergleiche
+
+- [i18next vs Intlayer](https://intlayer.org/de/blog/i18next-vs-intlayer) (Bibliotheksvergleich, gleiche Benchmark-Basis)
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/de/blog/next-intl-vs-intlayer-next-intl) (gleiche Adapter-Serie)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/de/blog/lingui-vs-intlayer-lingui) (gleiche Adapter-Serie)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/de/blog/vue-i18n-vs-intlayer-vue-i18n) (gleiche Adapter-Serie)
+- Migrationsanleitungen: [i18next](https://intlayer.org/de/doc/migration/i18next), [react-i18next](https://intlayer.org/de/doc/migration/react-i18next), [next-i18next](https://intlayer.org/de/doc/migration/next-i18next)
+- Adapter-Referenzen: [i18next](https://intlayer.org/de/doc/compatibility/i18next), [react-i18next](https://intlayer.org/de/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/de/doc/compatibility/next-i18next)
+
+## Fazit
+
+`i18next` ist die schwerste Runtime in diesem Benchmark, und die Adapter entfernen den Großteil davon, ohne dass Sie die gewohnte API aufgeben müssen. Auf derselben Next.js-App bedeutet das **68 KB weniger pro Seite** als im Basis-Setup, **12.7 KB weniger** als in der am stärksten handoptimierten Version, **8x kleinere Komponenten**, **0% Leakage** und **4 ms schnellere Hydration** für den Preis einer Konfigurationsdatei, einer Plugin-Zeile und einer Provider-Anpassung. Backends und Detektoren werden wirkungslos, `resources` wird ignoriert statt gemergt, und die native `next-intlayer`-Runtime bleibt nochmals 9 KB schlanker.
+
+Alle Rohdaten, Testanwendungen und Skripte stehen im [Benchmark Bloom Repository](https://github.com/intlayer-org/benchmark-bloom) bereit.
+
+Weitere Details finden Sie in der Dokumentation [Warum Intlayer?](https://intlayer.org/de/doc/why).