البدء في التدويل (i18n) مع Intlayer و Next.js باستخدام Page Router

ما هو Intlayer؟

Intlayer هي مكتبة تدويل (i18n) مبتكرة ومفتوحة المصدر مصممة لتبسيط دعم تعدد اللغات في تطبيقات الويب الحديثة. يتكامل Intlayer بسلاسة مع أحدث إطار عمل Next.js، بما في ذلك Page Router التقليدي الخاص به.

مع Intlayer، يمكنك:

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

يتوافق Intlayer مع Next.js 12 و 13 و 14 و 15. إذا كنت تستخدم Next.js App Router، فراجع دليل App Router. بالنسبة لـ Next.js 15، اتبع هذا الدليل.

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

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

قم بتثبيت الحزم اللازمة باستخدام مدير الحزم المفضل لديك:

npm install intlayer next-intlayer

• intlayer

الحزمة الأساسية التي توفر أدوات التدويل لإدارة التكوين، والترجمة، وإعلان المحتوى، والترجمة البرمجية، وأوامر CLI.

• next-intlayer

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

الخطوة 2: تكوين مشروعك

قم بإنشاء ملف تكوين لتعريف اللغات المدعومة من تطبيقك:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // أضف لغات أخرى هنا    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

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

الخطوة 3: دمج Intlayer مع تكوين Next.js

قم بتعديل تكوين Next.js الخاص بك لدمج Intlayer:

import { withIntlayer } from "next-intlayer/server";/** @type {import('next').NextConfig} */const nextConfig = {  // تكوين Next.js الحالي الخاص بك};export default withIntlayer(nextConfig);

يُستخدم مكون Next.js الإضافي withIntlayer() لدمج Intlayer مع Next.js. يضمن بناء ملفات إعلان المحتوى ومراقبتها في وضع التطوير. كما يعرّف متغيرات بيئة Intlayer ضمن بيئات Webpack أو Turbopack. بالإضافة إلى ذلك، يوفر أسماء مستعارة لتحسين الأداء ويضمن التوافق مع مكونات الخادم.

الخطوة 4: تكوين الوسيط لاكتشاف اللغة

قم بإعداد الوسيط لاكتشاف ومعالجة اللغة المفضلة للمستخدم تلقائيًا:

export { intlayerMiddleware as middleware } from "next-intlayer/middleware";export const config = {  matcher:    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",};

قم بتعديل معامل matcher ليتناسب مع مسارات تطبيقك. لمزيد من التفاصيل، راجع وثائق Next.js حول تكوين matcher.

الخطوة 5: تعريف مسارات اللغة الديناميكية

قم بتنفيذ التوجيه الديناميكي لتقديم محتوى محلي بناءً على لغة المستخدم.

1. إنشاء صفحات مخصصة لكل لغة:

   قم بإعادة تسمية ملف الصفحة الرئيسي ليشمل الجزء الديناميكي [locale].

   bash

   mv src/pages/index.tsx src/pages/[locale]/index.tsx

2. تحديث _app.tsx لمعالجة التوطين:

   قم بتعديل ملف _app.tsx ليشمل مزودي Intlayer.

   src/pages/_app.tsx

   import type { FC } from "react";import type { AppProps } from "next/app";import { IntlayerClientProvider } from "next-intlayer";const App = FC<AppProps>({ Component, pageProps }) => {  const { locale } = pageProps;  return (    <IntlayerClientProvider locale={locale}>      <Component {...pageProps} />    </IntlayerClientProvider>  );}export default MyApp;

3. إعداد getStaticPaths و getStaticProps:

   في ملف [locale]/index.tsx الخاص بك، عرّف المسارات والخصائص للتعامل مع اللغات المختلفة.

   src/pages/[locale]/index.tsx

   import type { FC } from "react";import type { GetStaticPaths, GetStaticProps } from "next";import { type Locales, getConfiguration } from "intlayer";const HomePage: FC = () => <div>{/* المحتوى الخاص بك هنا */}</div>;export const getStaticPaths: GetStaticPaths = () => {  const { internationalization } = getConfiguration();  const { locales } = internationalization;  const paths = locales.map((locale) => ({    params: { locale },  }));  return { paths, fallback: false };};export const getStaticProps: GetStaticProps = ({ params }) => {  const locale = params?.locale as string;  return {    props: {      locale,    },  };};export default HomePage;

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

الخطوة 6: إعلان المحتوى الخاص بك

قم بإنشاء وإدارة إعلانات المحتوى الخاصة بك لتخزين الترجمات.

import { t, type Dictionary } from "intlayer";const homeContent = {  key: "home",  content: {    title: t({      ar: "مرحبًا بكم في موقعي الإلكتروني",      en: "Welcome to My Website",      fr: "Bienvenue sur mon site Web",      es: "Bienvenido a mi sitio web",    }),    description: t({      ar: "ابدأ بتحرير هذه الصفحة.",      en: "Get started by editing this page.",      fr: "Commencez par éditer cette page.",      es: "Comience por editar esta página.",    }),  },} satisfies Dictionary;export default homeContent;

لمزيد من المعلومات حول إعلان المحتوى، راجع دليل إعلان المحتوى.

الخطوة 7: استخدام المحتوى في الكود الخاص بك

قم بالوصول إلى قواميس المحتوى الخاصة بك في جميع أنحاء تطبيقك لعرض المحتوى المترجم.

import type { FC } from "react";import { useIntlayer } from "next-intlayer";import { ComponentExample } from "@components/ComponentExample";const HomePage: FC = () => {  const content = useIntlayer("home");  return (    <div>      <h1>{content.title}</h1>      <p>{content.description}</p>      <ComponentExample />      {/* مكونات إضافية */}    </div>  );};// ... بقية الكود، بما في ذلك getStaticPaths و getStaticPropsexport default HomePage;

import type { FC } from "react";import { useIntlayer } from "next-intlayer";export const ComponentExample: FC = () => {  const content = useIntlayer("component-example"); // تأكد من وجود إعلان محتوى مطابق  return (    <div>      <h2>{content.title}</h2>      <p>{content.content}</p>    </div>  );};

عند استخدام الترجمات في خصائص string (مثل alt، title، href، aria-label)، استدعِ

قيمة الدالة كما يلي:

jsx

<img src={content.image.src.value} alt={content.image.value} />

لمعرفة المزيد عن الخطاف useIntlayer، راجع التوثيق.

(اختياري) الخطوة 8: تدويل بيانات التعريف الخاصة بك

في حال رغبتك في تدويل بيانات التعريف الخاصة بك، مثل عنوان الصفحة، يمكنك استخدام دالة getStaticProps التي يوفرها Next.js Page Router. بداخلها، يمكنك استرجاع المحتوى من دالة getIntlayer لترجمة بيانات التعريف الخاصة بك.

import { type Dictionary, t } from "intlayer";import { type Metadata } from "next";const metadataContent = {  key: "page-metadata",  content: {    title: t({      en: "Create Next App",      fr: "إنشاء تطبيق Next.js",      es: "إنشاء تطبيق Next.js",    }),    description: t({      en: "تم إنشاؤه بواسطة create next app",      fr: "تم إنشاؤه بواسطة create next app",      es: "تم إنشاؤه بواسطة create next app",    }),  },} satisfies Dictionary<Metadata>;export default metadataContent;

import { GetStaticPaths, GetStaticProps } from "next";import { getIntlayer, getMultilingualUrls } from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({  metadata,  multilingualUrls,  locale,}) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* توليد علامات hreflang لتحسين محركات البحث */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link key={lang} rel="alternate" hrefLang={lang} href={url} />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* محتوى الصفحة */}      <main>{/* محتوى صفحتك هنا */}</main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params,}) => {  const locale = params?.locale as string;  const metadata = getIntlayer("page-metadata", locale);  /**   * ينشئ كائن يحتوي على جميع الروابط لكل لغة.   *   * مثال:   * ```ts   *  getMultilingualUrls('/about');   *   *  // يعيد   *  // {   *  //   en: '/about',   *  //   fr: '/fr/about',   *  //   es: '/es/about',   *  // }   * ```   */  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... باقي الكود بما في ذلك getStaticPaths

لاحظ أن دالة getIntlayer المستوردة من next-intlayer تُعيد المحتوى الخاص بك ملفوفًا داخل IntlayerNode، مما يسمح بالتكامل مع المحرر المرئي. في المقابل، دالة getIntlayer المستوردة من intlayer تُعيد المحتوى الخاص بك مباشرةً بدون خصائص إضافية.

بدلاً من ذلك، يمكنك استخدام دالة getTranslation لإعلان بيانات التعريف الخاصة بك. ومع ذلك، يُنصح باستخدام ملفات إعلان المحتوى لأتمتة ترجمة بيانات التعريف الخاصة بك وفصل المحتوى في مرحلة ما.

import { GetStaticPaths, GetStaticProps } from "next";import {  type IConfigLocales,  getTranslation,  getMultilingualUrls,} from "intlayer";import { useIntlayer } from "next-intlayer";import Head from "next/head";import type { FC } from "react";interface HomePageProps {  locale: string;  metadata: {    title: string;    description: string;  };  multilingualUrls: Record<string, string>;}const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {  const content = useIntlayer("page");  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />        {/* إنشاء علامات hreflang لتحسين محركات البحث */}        {Object.entries(multilingualUrls).map(([lang, url]) => (          <link            key={lang}            rel="alternate"            hrefLang={lang}            href={url}          />        ))}        <link rel="canonical" href={multilingualUrls[locale]} />      </Head>      {/* محتوى الصفحة */}      <main>        {/* محتوى صفحتك هنا */}      </main>    </div>  );};export const getStaticProps: GetStaticProps<HomePageProps> = async ({  params}) => {  const locale = params?.locale as string;  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);  const metadata = {    title: t<string>({      en: "My title",      fr: "Mon titre",      es: "Mi título",    }),    description: t({      en: "My description",      fr: "Ma description",      es: "Mi descripción",    }),  };  const multilingualUrls = getMultilingualUrls("/");  return {    props: {      locale,      metadata,      multilingualUrls,    },  };};export default HomePage;// ... بقية الكود بما في ذلك getStaticPaths

تعرّف على المزيد حول تحسين البيانات الوصفية في الوثائق الرسمية لـ Next.js.

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

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

import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";import Link from "next/link";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales } = useLocalePageRouter();  const { setLocaleCookie } = useLocaleCookie();  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <Link            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            key={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={() => setLocaleCookie(localeItem)}          >            <span>              {/* اللغة - مثل FR */}              {localeItem}            </span>            <span>              {/* اللغة بلغتها الأصلية - مثل Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* اللغة في اللغة الحالية - على سبيل المثال Francés مع تعيين اللغة الحالية إلى Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* اللغة بالإنجليزية - على سبيل المثال French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        ))}      </div>    </div>  );};

طريقة بديلة هي استخدام دالة setLocale المقدمة من الخطاف useLocale. هذه الدالة لن تسمح بتحميل الصفحة مسبقًا وستعيد تحميل الصفحة.

في هذه الحالة، بدون إعادة التوجيه باستخدام router.push، فقط كود الخادم الخاص بك سيغير لغة المحتوى.

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... بقية الكودconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>    التغيير إلى الفرنسية  </button>);

واجهة برمجة التطبيقات useLocalePageRouter هي نفسها useLocale. لمعرفة المزيد عن هوك useLocale، يرجى الرجوع إلى التوثيق.

مراجع التوثيق:

• هوك getLocaleName
• هوك getLocalizedUrl
• هوك getHTMLTextDir
• خاصية hrefLang
• lang attribute
• dir attribute
• aria-current attribute

(اختياري) الخطوة 10: إنشاء مكون رابط محلي

لضمان أن يتوافق تنقل تطبيقك مع اللغة الحالية، يمكنك إنشاء مكون Link مخصص. يقوم هذا المكون تلقائيًا بإضافة بادئة اللغة الحالية إلى عناوين URL الداخلية، بحيث عندما ينقر مستخدم يتحدث الفرنسية على رابط لصفحة "حول"، يتم توجيهه إلى /fr/about بدلاً من /about.

هذا السلوك مفيد لعدة أسباب:

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

فيما يلي تنفيذ لمكون Link محلي بلغة TypeScript:

"use client";import { getLocalizedUrl } from "intlayer";import NextLink, { type LinkProps as NextLinkProps } from "next/link";import { useLocale } from "next-intlayer";import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";/** * دالة مساعدة للتحقق مما إذا كان الرابط المعطى خارجيًا. * إذا بدأ الرابط بـ http:// أو https://، فإنه يعتبر خارجيًا. */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * مكون رابط مخصص يقوم بتكييف خاصية href بناءً على اللغة الحالية. * بالنسبة للروابط الداخلية، يستخدم `getLocalizedUrl` لإضافة بادئة اللغة إلى الرابط (مثلاً /fr/about). * هذا يضمن بقاء التنقل ضمن نفس سياق اللغة. */export const Link = forwardRef<  HTMLAnchorElement,  PropsWithChildren<NextLinkProps>>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {  const { locale } = useLocale();  const isExternalLink = checkIsExternalLink(href.toString());  // إذا كان الرابط داخليًا وتم توفير href صالح، احصل على الرابط المحلي.  const hrefI18n: NextLinkProps["href"] =    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;  return (    <NextLink href={hrefI18n} ref={ref} {...props}>      {children}    </NextLink>  );});Link.displayName = "Link";

كيف يعمل

• كشف الروابط الخارجية:
  تقوم دالة المساعدة checkIsExternalLink بتحديد ما إذا كان الرابط خارجيًا. تُترك الروابط الخارجية كما هي لأنها لا تحتاج إلى تعريب.

• استرجاع اللغة الحالية:

• تحديد اللغة الحالية:
  يوفر الخطاف useLocale اللغة الحالية (على سبيل المثال، fr للفرنسية).

• توطين عنوان URL:
  بالنسبة للروابط الداخلية (أي غير الخارجية)، يتم استخدام getLocalizedUrl لإضافة بادئة اللغة الحالية تلقائيًا إلى عنوان URL. هذا يعني أنه إذا كان المستخدم يتصفح باللغة الفرنسية، فإن تمرير /about كـ href سيُحوَّل إلى /fr/about.

• إرجاع الرابط:
  يُرجع المكون عنصر <a> مع عنوان URL المترجم، مما يضمن أن التنقل يتوافق مع اللغة المختارة.

من خلال دمج هذا المكون Link في جميع أنحاء تطبيقك، تحافظ على تجربة مستخدم متسقة وواعية باللغة، مع الاستفادة أيضًا من تحسين محركات البحث وسهولة الاستخدام.

(اختياري) الخطوة 11: تحسين حجم الحزمة الخاصة بك

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

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

npm install @intlayer/swc --save-dev

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

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

تكوين TypeScript

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

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

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

تكوين Git

للحفاظ على نظافة مستودعك وتجنب الالتزام بالملفات المُولدة، يُنصح بتجاهل الملفات التي تم إنشاؤها بواسطة Intlayer.

أضف الأسطر التالية إلى ملف .gitignore الخاص بك:

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

إضافة VS Code

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

التثبيت من سوق VS Code

تقدم هذه الإضافة:

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

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

موارد إضافية

• توثيق Intlayer: مستودع GitHub
• دليل القاموس: القاموس
• توثيق التهيئة: دليل التهيئة

باتباع هذا الدليل، يمكنك دمج Intlayer بفعالية في تطبيق Next.js الخاص بك باستخدام Page Router، مما يتيح دعمًا قويًا وقابلًا للتوسع للتدويل في مشاريع الويب الخاصة بك.

التقدم أكثر

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

تاريخ الوثيقة

• 5.5.10 - 2025-06-29: بدء التاريخ