Getting Started Internationalizing (i18n) with Intlayer and Next.js using Page Router

What is 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، اتبع هذا الدليل.

Step-by-Step Guide to Set Up Intlayer in a Next.js Application Using Page Router

Step 1: Install Dependencies

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

npm install intlayer next-intlayer

• intlayer

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

• next-intlayer

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

Step 2: Configure Your Project

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

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

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

Step 3: Integrate Intlayer with Next.js Configuration

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

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

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

Step 4: Configure Middleware for Locale Detection

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

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.

Step 5: Define Dynamic Locale Routes

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

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 أن يسبق تطبيقك بناء الصفحات الضرورية لجميع اللغات في توجيه Page Router في Next.js. تقلل هذه الطريقة من حسابات وقت التشغيل وتؤدي إلى تحسين تجربة المستخدم. لمزيد من التفاصيل، يُرجى الرجوع إلى وثائق Next.js حول getStaticPaths و getStaticProps.

Step 6: Declare Your Content

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

import { t, type DeclarationContent } from "intlayer";const homeContent = {  key: "home",  content: {    title: t({      en: "Welcome to My Website",      fr: "Bienvenue sur mon site Web",      es: "Bienvenido a mi sitio web",    }),    description: t({      en: "Get started by editing this page.",      fr: "Commencez par éditer cette page.",      es: "Comience por editar esta página.",    }),  },} satisfies DeclarationContent;export default homeContent;

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

Step 7: Utilize Content in Your Code

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

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، يُرجى الرجوع إلى الوثائق.

(Optional) Step 8: Internationalize Your Metadata

لتدويل البيانات الوصفية مثل عناوين الصفحات والأوصاف، استخدم دالة getStaticProps بالتعاون مع دالة getTranslationContent الخاصة بـ Intlayer.

import { GetStaticPaths, GetStaticProps } from "next";import { type IConfigLocales, getTranslationContent, Locales } from "intlayer";import { useIntlayer } from "next-intlayer";interface HomePageProps {  locale: string;  metadata: Metadata;}const HomePage = ({ metadata }: HomePageProps) => {  // يمكن استخدام البيانات الوصفية في الرأس أو مكونات أخرى حسب الحاجة  return (    <div>      <Head>        <title>{metadata.title}</title>        <meta name="description" content={metadata.description} />      </Head>      {/* محتوى إضافي */}    </div>  );};export const getStaticProps: GetStaticProps = async ({ params }) => {  const locale = params?.locale as string;  const t = <T,>(content: IConfigLocales<T>) =>    getTranslationContent(content, locale);  const metadata = {    title: t({      en: "My Website",      fr: "Mon Site Web",      es: "Mi Sitio Web",    }),    description: t({      en: "Welcome to my website.",      fr: "Bienvenue sur mon site Web.",      es: "Bienvenido a mi sitio web.",    }),  };  return {    props: {      locale,      metadata,    },  };};export default HomePage;// ... بقية الكود بما في ذلك getStaticPaths

(Optional) Step 9: Change the Language of Your Content

للسماح للمستخدمين بتغيير اللغات ديناميكيًا، استخدم دالة setLocale التي توفرها هوك useLocale.

import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocalePageRouter } from "next-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { locale, pathWithoutLocale, availableLocales, setLocale } =    useLocalePageRouter();  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <a            href={getLocalizedUrl(pathWithoutLocale, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}          >            <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>            <span>              {/* اللغة بنفس اللغة - مثل FR */}              {localeItem}            </span>          </a>        </li>      ))}    </ol>  );};

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

مراجع الوثائق:

• getLocaleName hook
• getLocalizedUrl hook
• getHTMLTextDir hook
• hrefLang attribute
• lang attribute
• dir attribute
• aria-current attribute

2. مثال على فوائد TypeScript:

   

   

Git Configuration

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

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

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

Additional Resources

• وثائق Intlayer: مستودع GitHub
• دليل إعلان المحتوى: إعلان المحتوى
• وثائق التكوين: دليل التكوين

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