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

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

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

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

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

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

ما هو مترجم Intlayer؟

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

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

القيود

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

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

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

الخطوة 1: تثبيت التبعيات

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

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: تهيئة مشروعك

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

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:

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:

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

الخطوة 5: اكتشاف اللغة في صفحاتك

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

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 بتحليل شفرتك المصدرية، وإنشاء الترجمات باستخدام موفر الذكاء الاصطناعي المهيأ، واستبدال السلاسل النصية بمحتوى محلي أثناء خطوة البناء. كل هذا يتم تلقائياً بالكامل.

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

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

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>);}

{key: "page-content",content: {  nodeType: "translation",  translation: {    en: {      getStartedByEditing: "Get started by editing",    },    fr: {      getStartedByEditing: "Commencez par éditer",    },    ar: {      getStartedByEditing: "ابدأ بالتعديل",    },  }}}

import { type FC } from "react";import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";import { getLocale } from "next-intlayer/server";const PageContent: FC = () => {const content = useIntlayer("page-content");return (  <>    <p>{content.getStartedByEditing}</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 لاختبار وملء الترجمات المفقودة من التعليمات البرمجية الخاصة بك.

npx intlayer test         # اختبر ما إذا كانت هناك ترجمات مفقودة

npx intlayer fill         # ملء الترجمات المفقودة

لمزيد من التفاصيل، راجع وثائق CLI

(اختياري) الخطوة 8: تهيئة وكيل التوجيه لاكتشاف اللغة

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

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).

(اختياري) الخطوة 8: تغيير لغة المحتوى الخاص بك

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

"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 الملحق ويستخدمه تلقائياً:

npm install @intlayer/swc --save-dev

ملاحظة: يتوفر هذا التحسين فقط لـ Next.js 13 وما فوق.

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

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

إعداد TypeScript

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

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

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

تهيئة Git

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

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

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

(اختياري) خطوة 1 : استخراج محتوى مكوناتك

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

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

لإعداده، يمكنك إضافة قسم compiler في ملف 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;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // استخراج المحتوى من المكونات إلى القواميس   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # أو npm run dev

ملحق VS Code

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

تثبيت من VS Code Marketplace

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

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

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

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

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