---
createdAt: 2025-11-25
updatedAt: 2025-11-25
title: تحسين حجم وأداء حزمة i18n
description: تقليل حجم حزمة التطبيق من خلال تحسين محتوى التدويل (i18n). تعلّم كيفية الاستفادة من tree shaking والتحميل الكسول للقواميس باستخدام Intlayer.
keywords:
  - تحسين الحزمة
  - أتمتة المحتوى
  - المحتوى الديناميكي
  - Intlayer
  - Next.js
  - JavaScript
  - React
slugs:
  - doc
  - concept
  - bundle-optimization
history:
  - version: 6.0.0
    date: 2025-11-25
    changes: بدء السجل
---

# تحسين حجم وأداء حزمة i18n

واحدة من أكثر التحديات شيوعًا مع حلول i18n التقليدية التي تعتمد على ملفات JSON هي إدارة حجم المحتوى. إذا لم يقم المطورون بفصل المحتوى يدويًا إلى مساحات أسماء، غالبًا ما ينتهي الأمر بالمستخدمين إلى تنزيل ترجمات لكل صفحة وربما لكل لغة لمجرد عرض صفحة واحدة.

على سبيل المثال، قد يؤدي تطبيق يحتوي على 10 صفحات مترجمة إلى 10 لغات إلى قيام المستخدم بتنزيل محتوى 100 صفحة، على الرغم من حاجته إلى **صفحة واحدة** فقط (الصفحة الحالية باللغة الحالية). هذا يؤدي إلى هدر في عرض النطاق الترددي وبطء في أوقات التحميل.

> لاكتشاف ذلك، يمكنك استخدام محلل الحزمة مثل `rollup-plugin-visualizer` (vite)، `@next/bundle-analyzer` (next.js)، أو `webpack-bundle-analyzer` (React CRA / Angular / إلخ).

**تحل Intlayer هذه المشكلة من خلال تحسين وقت البناء.** تقوم بتحليل الكود الخاص بك لاكتشاف القواميس المستخدمة فعليًا لكل مكون وتعيد حقن المحتوى الضروري فقط في الحزمة الخاصة بك.

## جدول المحتويات

<TOC />

## كيف تعمل

تستخدم Intlayer **نهجًا لكل مكون**. على عكس ملفات JSON العالمية، يتم تعريف المحتوى الخاص بك بجانب مكوناتك أو داخلها. خلال عملية البناء، تقوم Intlayer بـ:

1.  **تحليل** الكود الخاص بك للعثور على استدعاءات `useIntlayer`.
2.  **بناء** محتوى القاموس المقابل.
3.  **استبدال** استدعاء `useIntlayer` بكود محسن بناءً على تكوينك.

هذا يضمن أن:

- إذا لم يتم استيراد مكون، فلن يتم تضمين محتواه في الحزمة (إزالة الكود الميت).
- إذا تم تحميل مكون بشكل كسول، فسيتم أيضًا تحميل محتواه بشكل كسول.

## الإعداد حسب المنصة

### Next.js

يتطلب Next.js إضافة `@intlayer/swc` للتعامل مع التحويل، حيث يستخدم Next.js SWC في عمليات البناء.

> يتم تثبيت هذه الإضافة بشكل افتراضي لأن إضافات SWC لا تزال تجريبية لـ Next.js. قد يتغير ذلك في المستقبل.

### Vite

يستخدم Vite إضافة `@intlayer/babel` التي تدرج كاعتماد ضمن `vite-intlayer`. يتم تمكين التحسين بشكل افتراضي.

### Webpack

لتمكين تحسين الحزمة مع Intlayer على Webpack، تحتاج إلى تثبيت وتكوين إضافة Babel المناسبة (`@intlayer/babel`) أو SWC (`@intlayer/swc`).

### Expo / Lynx

تحسين الحزمة **غير متوفر بعد** لهذه المنصة. سيتم إضافة الدعم في إصدار مستقبلي.

## التكوين

يمكنك التحكم في كيفية تحسين Intlayer لحزمتك عبر خاصية `build` في ملف `intlayer.config.ts` الخاص بك.

```typescript fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH],
    defaultLocale: Locales.ENGLISH,
  },
  build: {
    optimize: true,
    importMode: "static", // أو 'dynamic'
    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
  },
};

export default config;
```

> يُنصح بالاحتفاظ بالخيار الافتراضي لـ `optimize` في معظم الحالات.

> راجع توثيق التكوين لمزيد من التفاصيل: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/configuration.md)

### خيارات البناء

الخيارات التالية متاحة ضمن كائن تكوين `build`:

| الخاصية               | النوع                           | القيمة الافتراضية               | الوصف                                                                                                                                                                                                              |
| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`optimize`**        | `boolean`                       | `undefined`                     | يتحكم فيما إذا كان تفعيل تحسين البناء ممكّنًا. إذا كانت القيمة `true`، يقوم Intlayer باستبدال استدعاءات القاموس بحقنات محسّنة. إذا كانت `false`، يتم تعطيل التحسين. من المثالي تعيينها إلى `true` في بيئة الإنتاج. |
| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | يحدد كيفية تحميل القواميس (انظر التفاصيل أدناه).                                                                                                                                                                   |
| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | أنماط Glob التي تحدد الملفات التي يجب على Intlayer فحصها للتحسين. استخدم هذا لاستبعاد الملفات غير المتعلقة وتسريع عمليات البناء.                                                                                   |
| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | يتحكم في تنسيق الإخراج للقواميس المبنية.                                                                                                                                                                           |

## أوضاع الاستيراد

تحدد إعدادات `importMode` كيفية حقن محتوى القاموس في مكونك.

### 1. الوضع الثابت (`default`)

في الوضع الثابت، يقوم Intlayer باستبدال `useIntlayer` بـ `useDictionary` ويحقن القاموس مباشرة في حزمة جافا سكريبت.

- **الإيجابيات:** عرض فوري (متزامن)، بدون طلبات شبكة إضافية أثناء التهيئة.
- **السلبيات:** الحزمة تتضمن ترجمات **لكل** اللغات المتاحة لذلك المكون المحدد.
- **الأفضل لـ:** تطبيقات الصفحة الواحدة (SPA).

**مثال على الكود المحول:**

```tsx
// كودك
const content = useIntlayer("my-key");

// الكود المحسن (الوضع الثابت)
const content = useDictionary({
  key: "my-key",
  content: {
    nodeType: "translation",
    translation: {
      en: "My title",
      fr: "Mon titre",
    },
  },
});
```

### 2. الوضع الديناميكي

في الوضع الديناميكي، يستبدل Intlayer الدالة `useIntlayer` بـ `useDictionaryAsync`. تستخدم هذه الدالة `import()` (آلية تشبه Suspense) لتحميل ملف JSON الخاص باللغة الحالية بشكل كسول.

- **الإيجابيات:** **تحسين على مستوى اللغة (Locale-level tree shaking).** المستخدم الذي يعرض النسخة الإنجليزية سيقوم بتحميل قاموس اللغة الإنجليزية فقط. قاموس اللغة الفرنسية لن يتم تحميله أبدًا.
- **السلبيات:** يؤدي إلى طلب شبكة (جلب الأصول) لكل مكون أثناء عملية التهيئة (hydration).
- **الأفضل لـ:** كتل نصية كبيرة، مقالات، أو تطبيقات تدعم العديد من اللغات حيث يكون حجم الحزمة أمرًا حاسمًا.

**مثال على الكود المحول:**

```tsx
// Your code
const content = useIntlayer("my-key");

// Optimized code (Dynamic)
const content = useDictionaryAsync({
  en: () =>
    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
      (mod) => mod.default
    ),
  fr: () =>
    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
      (mod) => mod.default
    ),
});
```

> عند استخدام `importMode: 'dynamic'`، إذا كان لديك 100 مكون يستخدم `useIntlayer` في صفحة واحدة، سيحاول المتصفح إجراء 100 طلب تحميل منفصل. لتجنب هذا "تسلسل" الطلبات، قم بتجميع المحتوى في عدد أقل من ملفات `.content` (مثل قاموس واحد لكل قسم من الصفحة) بدلاً من واحد لكل مكون ذرة.

> حاليًا، `importMode: 'dynamic'` غير مدعوم بالكامل لـ Vue و Svelte. يُنصح باستخدام `importMode: 'static'` لهذه الأُطُر حتى صدور تحديثات لاحقة.

### 3. الوضع الحي (Live Mode)

يتصرف بشكل مشابه للوضع الديناميكي لكنه يحاول أولاً جلب القواميس من واجهة برمجة تطبيقات المزامنة الحية Intlayer Live Sync API. إذا فشل استدعاء API أو لم يكن المحتوى معلمًا للتحديثات الحية، فإنه يعود إلى الاستيراد الديناميكي.

> راجع توثيق CMS لمزيد من التفاصيل: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ar/intlayer_CMS.md)

## الملخص: الوضع الثابت مقابل الوضع الديناميكي

| الميزة                   | الوضع الثابت                             | الوضع الديناميكي                                    |
| :----------------------- | :--------------------------------------- | :-------------------------------------------------- |
| **حجم حزمة جافا سكريبت** | أكبر (يشمل جميع اللغات للمكون)           | الأصغر (كود فقط، بدون محتوى)                        |
| **التحميل الأولي**       | فوري (المحتوى موجود في الحزمة)           | تأخير بسيط (يجلب JSON)                              |
| **طلبات الشبكة**         | 0 طلبات إضافية                           | طلب واحد لكل قاموس                                  |
| **Tree Shaking**         | على مستوى المكون                         | على مستوى المكون + مستوى اللغة                      |
| **أفضل استخدام**         | مكونات واجهة المستخدم، التطبيقات الصغيرة | الصفحات التي تحتوي على نصوص كثيرة، العديد من اللغات |
