Creation:2026-01-10Last update:2026-05-31

    كيفية جعل تطبيق Next.js الحالي متعدد اللغات (i18n) (دليل i18n 2026)

    www.youtube.com

    راجع قالب التطبيق على GitHub.

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

    لماذا يصعب تدويل تطبيق موجود بالفعل؟

    إذا حاولت يومًا إضافة لغات متعددة إلى تطبيق صُمم للغة واحدة فقط، فأنت تعرف المعاناة. الأمر ليس مجرد "صعب" - إنه ممل. عليك أن تستعرض كل ملف، وتستخرج كل سلسلة نصية، وتنقلها إلى ملفات قواميس منفصلة.

    ثم يأتي الجزء المحفوف بالمخاطر: استبدال كل هذا النص بخطافات (hooks) التعليمات البرمجية دون كسر التخطيط أو المنطق. إنه نوع العمل الذي يوقف تطوير الميزات الجديدة لأسابيع ويبدو وكأنه إعادة هيكلة لا تنتهي.

    ما هو مترجم Intlayer؟

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

    وثائق المترجم: /ar/doc/compiler

    القيود

    نظرًا لأن المترجم يقوم بتحليل التعليمات البرمجية وتحويلها (إدراج الخطافات وإنشاء القواميس) في وقت التجميع (compile time)، فقد يؤدي إلى إبطاء عملية البناء لتطبيقك.

    للتخفيف من هذا التأثير أثناء التطوير، يمكنك ضبط المترجم للعمل في وضع 'build-only' أو تعطيله عند عدم الحاجة إليه.

    دليل خطوة بخطوة لإعداد Intlayer في تطبيق Next.js

    1. تثبيت التبعيات

      قم بتثبيت الحزم اللازمة باستخدام npm:

      bash
      npm install intlayer next-intlayernpm install @intlayer/babel --save-devnpx intlayer init

      • intlayer

        الحزمة الأساسية التي توفر أدوات التدويل لإدارة التهيئة، الترجمة، إعلان المحتوى، والترجمة البرمجية (transpilation)، بالإضافة إلى أوامر CLI.

      • next-intlayer

        الحزمة التي تدمج Intlayer مع Next.js. وتوفر موفري السياق (context providers) والخطافات للتدويل في Next.js. بالإضافة إلى ذلك، تتضمن الملحق لـ Next.js لدمج Intlayer مع Webpack أو Turbopack، بالإضافة إلى وسيط (middleware) لاكتشاف اللغة المفضلة للمستخدم، وإدارة ملفات تعريف الارتباط، ومعالجة إعادة توجيه عناوين URL.

    2. تهيئة مشروعك

      قم بإنشاء ملف تهيئة لتحديد لغات تطبيقك:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.ARABIC],    defaultLocale: Locales.ARABIC,  },  routing: {    mode: "search-params",  },  compiler: {    /**     * يشير إلى ما إذا كان يجب تمكين المجمّع.     */    enabled: true,    /**     * دليل الإخراج للقواميس المحسنة.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * أدخل المحتوى فقط في الملف الذي تم إنشاؤه، بدون مفتاح.     */    noMetadata: false,    /**     * بادئة مفتاح القاموس     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * يشير إلى ما إذا كان يجب حفظ المكونات بعد تحويلها.     * بهذه الطريقة، يمكن تشغيل المجمّع مرة واحدة فقط لتحويل التطبيق، ثم يمكن إزالته.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "هذا التطبيق هو مثال بسيط لتطبيق خرائط",  },};export default config;
      ملاحظة: تأكد من إعداد OPEN_AI_API_KEY في متغيرات البيئة الخاصة بك.
      من خلال ملف التهيئة هذا، يمكنك إعداد عناوين URL المحلية، وعمليات إعادة توجيه الوكيل، وأسماء ملفات تعريف الارتباط، وموقع وامتداد إعلانات المحتوى الخاصة بك، وتعطيل سجلات Intlayer في وحدة التحكم، والمزيد. للحصول على قائمة كاملة بالمعلمات المتاحة، راجع توثيق التهيئة.

    3. دمج Intlayer في تهيئة Next.js الخاصة بك

      قم بتهيئة إعداد Next.js الخاص بك لاستخدام Intlayer:

      next.config.ts
      import type { NextConfig } from "next";import { withIntlayer } from "next-intlayer/server";const nextConfig: NextConfig = {  /* خيارات تهيئة Next.js اختيارية هنا */};export default withIntlayer(nextConfig);
      يُستخدم ملحق Next.js withIntlayer() لدمج Intlayer مع Next.js. وهو يضمن بناء ملفات إعلام المحتوى ومراقبتها في وضع التطوير. يحدد متغيرات بيئة Intlayer داخل بيئات Webpack أو Turbopack. بالإضافة إلى ذلك، يوفر أسماء مستعارة لتحسين الأداء ويضمن التوافق التام مع مكونات الخادم.

    4. تكوين Babel

      يتطلب مترجم Intlayer استخدام Babel لاستخراج المحتوى الخاص بك وتحسينه. قم بتحديث babel.config.js (أو babel.config.json) لتضمين إضافات Intlayer:

      babel.config.js
      const {  intlayerExtractBabelPlugin,  intlayerOptimizeBabelPlugin,  getExtractPluginOptions,  getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = {  presets: ["next/babel"],  plugins: [    [intlayerExtractBabelPlugin, getExtractPluginOptions()],    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],  ],};

    5. اكتشاف اللغة في صفحاتك

      قم بإخلاء محتوى RootLayout الخاص بك واستبدله بالمثال التالي:

      src/app/layout.tsx
      import type { Metadata } from "next";import type { ReactNode } from "react";import "./globals.css";import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";import { getHTMLTextDir, getIntlayer } from "intlayer";import { getLocale } from "next-intlayer/server";export { generateStaticParams } from "next-intlayer";export const generateMetadata = async (): Promise<Metadata> => {  const locale = await getLocale();  const { title, description, keywords } = getIntlayer("metadata", locale);  return {    title,    description,    keywords,  };};const RootLayout = async ({  children,}: Readonly<{  children: ReactNode;}>) => {  const locale = await getLocale();  return (    <html lang={locale} dir={getHTMLTextDir(locale)}>      <IntlayerClientProvider defaultLocale={locale}>        <body>{children}</body>      </IntlayerClientProvider>    </html>  );};export default RootLayout;

    6. ترجمة مكوناتك برمجياً

      مع تمكين المترجم، لم تعد بحاجة للإعلان عن قواميس المحتوى يدويًا (مثل ملفات .content.ts).

      بدلاً من ذلك، يمكنك كتابة المحتوى الخاص بك مباشرةً في شفرتك كتسلسلات نصية (strings) مكتوبة يدوياً. سيقوم Intlayer بتحليل شفرتك المصدرية، وإنشاء الترجمات باستخدام موفر الذكاء الاصطناعي المهيأ، واستبدال السلاسل النصية بمحتوى محلي أثناء خطوة البناء. كل هذا يتم تلقائياً بالكامل.

      ما عليك سوى كتابة مكوناتك باستخدام سلاسل نصية ثابتة بلغتك الافتراضية. يتولى المترجم الباقي.

      مثال على ما قد تبدو عليه صفحتك:

      src/app/page.tsx
      import type { FC } from "react";import { IntlayerServerProvider } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {return (  <>    <p>ابدأ بالتعديل</p>    <code>src/app/page.tsx</code>  </>);};export default async function Page() {const locale = await getLocale();return (  <IntlayerServerProvider locale={locale}>    <PageContent />  </IntlayerServerProvider>);}
      • يُستخدم IntlayerClientProvider لتوفير اللغة للأبناء في جانب العميل.

      • بينما يُستخدم IntlayerServerProvider لتوفير اللغة للأبناء في جانب الخادم.

        Layout and page cannot share a common server context because the server context system is based on a per-request data store (via React's cache mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.

    7. ملء الترجمات المفقودة

      اختياري

      يوفر Intlayer أداة CLI لمساعدتك في ملء الترجمات المفقودة. يمكنك استخدام الأمر intlayer لاختبار وملء الترجمات المفقودة من التعليمات البرمجية الخاصة بك.

      bash
      npx intlayer test         # اختبر ما إذا كانت هناك ترجمات مفقودة
      bash
      npx intlayer fill         # ملء الترجمات المفقودة
      لمزيد من التفاصيل، راجع وثائق CLI

    8. تهيئة وكيل التوجيه لاكتشاف اللغة

      اختياري

      قم بتهيئة وسيط (middleware) للوكيل لاكتشاف لغة المستخدم المفضلة تلقائياً:

      src/proxy.ts
      export { intlayerProxy as proxy } from "next-intlayer/proxy";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};
      يستخدم intlayerProxy لاكتشاف اللغة المفضلة للمستخدم وإعادة توجيهه إلى عنوان URL المناسب كما هو محدد في إعدادات ملف التهيئة. بالإضافة إلى ذلك، فإنه يتيح حفظ لغة المستخدم المفضلة في ملف تعريف ارتباط (cookie).

    9. تغيير لغة المحتوى الخاص بك

      اختياري

      لتغيير لغة المحتوى في Next.js، الطريقة الموصى بها هي استخدام مكون Link لإعادة توجيه المستخدمين إلى الصفحة المحلية المقابلة. يسمح مكون Link بالتحميل المسبق (prefetching) للصفحة، مما يساعد على تجنب تحديث الصفحة بالكامل.

      src/components/localeSwitcher/LocaleSwitcher.tsx
      "use client";import type { FC } from "react";import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";import { useLocale } from "next-intlayer";export const LocaleSwitcher: FC = () => {  const { locale, availableLocales, setLocale } = useLocale();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocale(localeItem)}          >            <span>              {/* اللغة - مثل: AR */}              {localeItem}            </span>            <span>              {/* اللغة بلغتها الخاصة - مثل: العربية */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* اللغة باللغة الحالية - مثل: Francés عندما تكون اللغة الحالية هي Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* اللغة بالإنجليزية - مثل: Arabic */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </button>        ))}      </div>    </div>  );};
      الطريقة البديلة هي استخدام وظيفة setLocale التي يوفرها خطاف useLocale. لن تسمح هذه الوظيفة بالتحميل المسبق للصفحة. راجع وثائق خطاف useLocale لمزيد من التفاصيل.

    10. تحسين حجم البندل الخاصة بك

      اختياري

      عند استخدام next-intlayer ، يتم تضمين القواميس في الحزمة لكل صفحة بشكل افتراضي. لتحسين حجم البندل ، يوفر Intlayer ملحق SWC اختيارياً يستبدل بذكاء استدعاءات useIntlayer باستخدام الماكرو. يضمن ذلك تضمين القواميس فقط في حزم الصفحات التي تستخدمها بالفعل.

      لتمكين هذا التحسين ، قم بتثبيت حزمة @intlayer/swc. بمجرد التثبيت ، سيكتشف next-intlayer الملحق ويستخدمه تلقائياً:

      bash
      npm install @intlayer/swc --save-dev
      ملاحظة: يتوفر هذا التحسين فقط لـ Next.js 13 وما فوق.
      ملاحظة: لا يتم تثبيت هذه الحزمة بشكل افتراضي لأن ملحقات SWC لا تزال تجريبية في Next.js. قد يتغير هذا في المستقبل.

      ملاحظة: إذا قمت بتعيين الخيار كـ importMode: 'dynamic' أو importMode: 'fetch' (في تهيئة dictionary) ، فسوف يعتمد على Suspense ، لذا سيتعين عليك لف استدعاءات useIntlayer بحدود Suspense. هذا يعني أنك لن تكون قادرًا على استخدام useIntlayer مباشرة في المستوى العلوي لمكون الصفحة / التخطيط الخاص بك.

    11. استخراج محتوى مكوناتك

      اختياري

      إذا كان لديك قاعدة بيانات كود موجودة، فقد يكون تحويل آلاف الملفات مستهلكًا للوقت.

      لتسهيل هذه العملية، يقترح Intlayer مترجمًا / مستخرجًا لتحويل مكوناتك واستخراج المحتوى.

      لإعداده، يمكنك إضافة قسم compiler في ملف intlayer.config.ts الخاص بك:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... بقية التكوين الخاص بك
  compiler: {
    /**
     * يشير إلى ما إذا كان يجب تمكين المترجم.
     */
    enabled: true,

    /**
     * يحدد مسار ملفات المخرجات
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * يشير إلى ما إذا كان يجب حفظ المكونات بعد تحويلها. بهذه الطريقة، يمكن تشغيل المترجم مرة واحدة فقط لتحويل التطبيق، ثم يمكن إزالته.
     */
    saveComponents: false,

    /**
     * بادئة مفتاح القاموس
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى

      bash
      npx intlayer extract

    إعداد TypeScript

    يستخدم Intlayer ميزة "توسيع الوحدات" (module augmentation) للاستفادة من مزايا TypeScript وجعل قاعدة الكود الخاصة بك أكثر قوة.

    منشئ التعليمات البرمجية

    توضيحات إبراز الخطأ في الكود

    تأكد من أن تهيئة TypeScript الخاصة بك تتضمن الأنواع التي تم إنشاؤها تلقائياً.

    tsconfig.json
    {  // ... تهيئات TypeScript الحالية  "include": [    // ... تهيئات TypeScript الحالية    ".intlayer/**/*.ts", // تضمين الأنواع المنشأة تلقائياً  ],}

    تهيئة Git

    من المستحسن تجاهل الملفات التي تم إنشاؤها بواسطة Intlayer. يتيح لك ذلك تجنب إضافتها إلى مستودع Git الخاص بك.

    للقيام بذلك ، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:

    .gitignore
    # تجاهل الملفات المنشأة بواسطة Intlayer.intlayer

    ملحق VS Code

    لتحسين تجربة التطوير الخاصة بك مع Intlayer ، يمكنك تثبيت ملحق Intlayer الرسمي لـ VS Code.

    تثبيت من VS Code Marketplace

    يوفر هذا الملحق:

    • الإكمال التلقائي لمفاتيح الترجمة.
    • اكتشاف الأخطاء في الوقت الفعلي للترجمات المفقودة.
    • معاينات مضمنة للمحتوى المترجم.
    • إجراءات سريعة لإنشاء وتحديث الترجمات بسهولة.

    لمزيد من التفاصيل حول استخدام الملحق ، راجع وثائق ملحق Intlayer لـ VS Code.

    اذهب أبعد من ذلك

    للذهاب إلى أبعد من ذلك، يمكنك تنفيذ المحرر المرئي أو إضفاء الطابع الخارجي على المحتوى الخاص بك باستخدام نظام إدارة المحتوى (CMS).

    Next.js وموجه الصفحة
    Tanstack Start