كيفية اختيار مكتبة React i18n المناسبة

لا توفر React أي عنصر أولي (primitive) مدمج للتدويل (i18n). المكتبة التي تختارها من اليوم الأول تحدد كيفية تخزين الترجمات، وكيفية وصولها إلى الحزمة (bundle)، ومقدار العمل اليدوي الذي سيبقى على عاتقك للسنوات القليلة القادمة. تختار معظم الفرق بناءً على الشعبية فقط، ثم تكتشف التنازلات المعمارية عند الوصول إلى 2,000 مفتاح.

يسلك هذا الدليل الاتجاه المعاكس: أجب عن بعض الأسئلة حول مشروعك أولاً، ثم طابق الإجابات مع المكتبات المناسبة. يركز هذا الدليل على تطبيقات React البسيطة (Vite و React Router و TanStack Start). لدى Next.js قيودها الخاصة، والتي تم تناولها في مقارنة Next.js.

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

ستة أسئلة للإجابة عليها قبل مقارنة المكتبات

جدول المقارنة لا فائدة منه دون معرفة الصفوف التي تهمك فعلاً. راجع هذه الأسئلة أولاً.

1. كيف يتم تصيير (render) التطبيق؟ هل هو SPA فقط، أم SSR مع التروية (hydration)، أم React Server Components؟ تعمل خطافات (hooks) السياق (Context-based) في كل مكان في تطبيقات SPA. أما مع RSC، يفرض الـ hook إضافة "use client" على كل مكون يعرض نصاً، وبالتالي ستحتاج إلى server-side API أيضاً.
2. من يكتب الترجمات؟ المطورون، أم فريق داخلي يستخدم نظام إدارة الترجمة (TMS)، أم وكالة تسلم ملفات ICU، أم خط أنابيب ذكاء اصطناعي (AI pipeline)؟ يحدد هذا تنسيق الكتالوج أكثر من أي تفصيل في الـ API.
3. كم عدد اللغات والصفحات؟ لغتان وخمس صفحات يمكنها تحمل تضمين كل شيء في الحزمة. أما عشر لغات وخمسون مساراً فلا يمكنها ذلك، وتصبح استراتيجية التحميل هي التكلفة الأساسية.
4. هل تحتاج إلى أمان الأنواع على المفاتيح (types on keys)؟ الخطأ الإملائي في t("checkout.totl") يتم تجميعه بنجاح في جميع المكتبات المعتمدة على المفاتيح ما لم تقم بإعداد الأنواع بنفسك. قرر ما إذا كان ذلك مقبولاً لديك.
5. ماذا يحتوي النص؟ نص عادي، أم صيغ جمع (plurals)، أم جمل تتوسطها روابط <Link>؟ المحتوى الغني (Rich content) هو النقطة التي تصبح فيها معظم واجهات برمجة التطبيقات معقدة.
6. كم من الوقت سيستمر المشروع؟ نموذج أولي مدته ثلاثة أشهر لا يحتاج إلى نفس قدر أدوات البناء التي يحتاجها منتج مدته خمس سنوات.

اكتب الإجابات، فكل ما يلي يستند إليها.

المشهد العام في صورة واحدة

خمسة عشر عاماً من JavaScript i18n تتلخص في أربع موجات معمارية، وتأتي مكتبات React التي ستقارن بينها من موجات مختلفة.

يوضح مقال تاريخ JavaScript i18n بالتفصيل كيف عالجت كل موجة مشاكل الموجة السابقة.

القرار الأكثر أهمية: أين يعيش المحتوى ومتى يتم تحميله

تمتلك كل مكتبة React i18n نفس الهيكل الأساسي: مخزن (store)، ومزود (provider)، وخطاف (hook). كل ما يستقبله الـ provider ينتهي به المطاف في حزمة العميل (client bundle) أو في حمولة التروية (hydration payload). لذا فإن الخيارين الهيكليين هما:

• محتوى مركزي أو محدد النطاق (scoped). ملف en.json واحد للتطبيق بأكمله، أو تصريح واحد لكل مكون (أو لكل namespace).
• استيراد ثابت (static) أو ديناميكي (dynamic). تجميع كل شيء عند بدء التشغيل، أو جلب اللغة والمسار النشطين عند الطلب.

يوضح الرسم البياني أدناه تقديراً للحمولة لتطبيق نظري يتكون من 1 إلى 10 صفحات، مترجم إلى 1 إلى 10 لغات، مع حوالي 30 كيلوبايت من النصوص لكل صفحة.

المحتوى المركزي ذو الاستيراد الثابت ينمو مع كلا المحورين: 10 صفحات مضروبة في 10 لغات تعني 300 كيلوبايت من النصوص في كل صفحة. الاستيرادات الديناميكية تلغي محور اللغات، وتحديد النطاق (scoping) يلغي محور الصفحات. الدمج بينهما فقط هو ما يبقي الحجم ثابتاً ومسطحاً.

هذه ليست ميزة مكتبة فحسب، بل هي مسألة انضباط برمجي. يمكن تقسيم react-i18next عبر namespaces و lazy backends. ويمكن تقسيم use-intl لكل مسار. ولكن لا يوجد ما يفرض ذلك تلقائياً، ومكون <Button> مشترك يستدعي t("common:cta") يجعل common بهدوء اعتمادية لجميع المسارات. يقيس اختبار الأداء (benchmark) هذا تحت مسمى "التسريب من المسارات الأخرى" و"التسريب من اللغات الأخرى"، وهو مصدر معظم الفجوة بين المكتبات.

إذا كانت إجابتك على السؤال 3 هي "لغات متعددة وصفحات متعددة"، فركز على هذا القسم أكثر من أي تفضيل لواجهة الـ API. يتعمق مقال الـ i18n لكل مكون مقابل المركزي في جانب الصيانة لهذا الخيار.

الخيارات المرشحة

أحجام المكتبات مأخوذة من اختبار أداء TanStack Start: الـ provider بالإضافة إلى الـ hook في مكون فارغ، بعد التجميع والـ tree-shaking والـ minification، لـ 10 صفحات و10 لغات. يتم قياس المحتوى بشكل منفصل.

الأرقام تمثل لقطة لإصدارات benchmark وتتغير مع التحديثات. قم بتشغيل اختبار الأداء على تطبيقك الخاص قبل اتخاذ القرار بناءً على الحجم وحده.

أمران لا يظهرهما الجدول: لا تشحن Paraglide أي مكتبة تقريباً لأنها تولد الكود داخل مستودعك، مما يعني خطوة إعادة توليد قبل كل commit وتعارضات دمج (merge conflicts) محتملة في الملفات المولدة. كما تتطلب Intlayer إضافة أداة تجميع (vite-intlayer أو ما يعادلها)، لذا لا يمكن تشغيلها في بيئة بدون أدوات بناء (no-build setup).

مطابقة إجاباتك مع المكتبة المناسبة

نقاط القصور في كل مكتبة

حدود صريحة، لأن كل خيار ينطوي على عيوب.

• react-i18next: الأثقل بين المجموعة، تنسيق جمع خاص بها، الأنواع تتطلب إعداداً يدوياً وصيانة مستمرة، وتتراكم المفاتيح غير المستخدمة دون تنبيه.
• react-intl: تجربة مطور مطولة (useIntl() ثم formatMessage({ id }))، ومثيل عام مرتبط بعدة عقد.
• use-intl: سهلة في البداية، وصعبة في التحسين. الـ namespaces والتحميل الديناميكي والأنواع معاً تبطئ عملية التطوير كثيراً.
• Lingui: خطوة بناء إضافية لـ extract و compile، وعدة صيغ متداخلة (t()، القوالب ذات العلامات، i18n.t()، <Trans>) تربك كلاً من المطورين ومساعدي الذكاء الاصطناعي.
• Paraglide: ملفات مولدة داخل المستودع، لم يدخل الـ tree-shaking حيز التنفيذ الكامل في اختبار React، ويتم قراءة اللغة من التخزين في كل عقدة بدلاً من قراءتها من المخزن المركزي.
• Tolgee: لا توجد أنواع للمفاتيح، إعداد أصعب، والتحرير المباشر داخل السياق هو نقطة البيع الأساسية.
• Intlayer: إضافة بناء إلزامية، نظام بيئي أصغر، دعم جزئي لـ ICU، وتوزيع المحتوى عبر قاعدة الكود يعني أن تصدير ملف JSON واحد للمترجم يتطلب أدوات إضافية.
• gt-react, lingo.dev: غير موصى بهما في اختبار الأداء: أخطاء حصص الاستخدام (quota) أثناء البناء، والارتباط بمزود معين (vendor lock-in)، ومشاكل تفاعلية تطلبت إجبار الـ provider على إعادة التصيير.

كيف يبدو كل خيار في الكود

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

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      ar: "عربة التسوق الخاصة بك",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      ar: plural({ one: "{{count}} عنصر", other: "{{count}} عناصر" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

هل تستخدم بالفعل react-i18next أو react-intl أو Lingui؟ تتيح محولات التوافق (react-i18next، و react-intl، و Lingui) إنشاء أسماء مستعارة (aliases) للاستيرادات على مستوى أداة التجميع بحيث تستمر واجهة الـ API الحالية في العمل أثناء نقلك للمكونات واحداً تلو الآخر. يغطي دليل الهجرة باقي التفاصيل.

قبل أن تعتمد اختيارك النهائي

يخبرك جدول الميزات بما تفعله المكتبة اليوم. وتوضح لك هذه النقاط كيف ستكون تجربة العمل بها على المدى الطويل.

تحقق من نشاط المستودع.

الالتزامات (commits)، وسرعة الرد على المشكلات (issues)، وما إذا كان آخر إصدار فرعي قد صدر هذا العام. التصميم السليم بدون مسؤول صيانة يعني أنك ستواجه هجرة إجبارية مستقبلاً.

لا تختر بناءً على عدد تنزيلات npm فقط.

المكتبة الأكثر تثبيتاً هي أول مكتبة ظهرت، وليست بالضرورة المكتبة التي تناسب كود React في عام 2026. تقيس التنزيلات التاريخ وليس الملاءمة الحالية.

اسأل من يدعم مسؤول الصيانة، وماذا يبيعون.

تحظى i18next بدعم من Locize. وتدعم Crowdin كلاً من next-intl / use-intl و vue-i18n و svelte-i18n و Lingui. تدير كل من Tolgee و Paraglide (inlang) و Intlayer منصتها الخاصة. المزود الذي يعتمد دخله على الترجمة المستضافة لديه القليل من الدوافع لجعل الترجمة مجانية داخل سلسلة أدواتك. تعد Intlayer الوحيدة في المجموعة التي توفر ترجمة بالذكاء الاصطناعي عبر الـ CLI باستخدام مفتاح API الخاص بك، مع نظام إدارة محتوى (CMS) يمكنك استضافته ذاتياً.

هل المكتبة جاهزة لوكلاء الذكاء الاصطناعي (AI agents)؟

لا يزال الوكلاء يواجهون صعوبات مع التدويل: ينسون اللغات، ويخترعون مفاتيح من عندهم، ويخلطون بين صيغ الرسائل. هل توفر المكتبة Agent Skills أو خادم MCP حتى يتمكن الوكيل من سرد المحتوى وملئه واختباره؟ وهل يتم تحسين تحميل المحتوى افتراضياً، أم يتعين على شخص ما مراجعة الـ namespaces والاستيرادات الكسولة كل ربع سنة؟

أمان الأنواع فور التثبيت.

ليس "يمكن توفير الأنواع مع إعداد إضافي"، بل "المفتاح الخاطئ يفشل tsc في تثبيت جديد". تحقق مما يحدث مع مفتاح غير موجود، ومع لغة تفتقد ترجمة واحدة.

اكتشاف المحتوى غير المستخدم.

الكتالوجات تنمو باستمرار ولا تصغر من تلقاء نفسها. تقوم عملية بناء Intlayer بحذف الحقول غير المستخدمة وتسجيلها (build.purge). وتحقق Paraglide ذلك معمارياً، حيث يتم التخلص من دالة الرسالة غير المستدعاة عبر tree-shaking. أما باقي المكتبات فتترك مهمة تنظيف الكتالوجات عليك.

تجربة المطور (DX).

الوقت المستغرق من الإعداد حتى أول نص مترجم، ووجود LSP أو إضافة VS Code تعرض الترجمة عند التمرير وتنتقل إلى التصريح مباشرة، و CLI للملء والاختبار والرفع، وطريقة لغير المطورين لتحرير المحتوى (المحرر المرئي أو نظام إدارة المحتوى (CMS)) بدون طلب سحب (pull request).

الأسئلة الشائعة

للمزيد من التفاصيل

• اختبار أداء مكتبات i18n: حجم الحزمة والتسريب وتوقيت تبديل اللغة و تقرير TanStack Start
• React i18n: كيف يعمل نموذج المزود (provider) وتكلفته
• react-i18next مقابل react-intl مقابل Intlayer، ميزة بميزة
• next-i18next مقابل next-intl مقابل Intlayer
• تاريخ JavaScript i18n
• الـ i18n المعتمد على المترجم مقابل التصريحي
• الـ i18n لكل مكون مقابل المركزي
• كيف يعمل تحسين الحزمة في وقت البناء
• إعداد i18n في تطبيق Vite + React
• نفس الدليل لكل من Vue، و Svelte، و Solid