Documentation

بيئة

Intlayer مع Next.js

Getting Started internationalizing (i18n) with Intlayer and Next.js 15 App Router

What is Intlayer?

Intlayer هي مكتبة مبتكرة ومفتوحة المصدر لترجمة المحتوى (i18n) مصممة لتبسيط دعم تعدد اللغات في تطبيقات الويب الحديثة. يتكامل Intlayer بسلاسة مع إطار العمل Next.js 15 الأحدث، بما في ذلك App Router القوي. تم تحسينه للعمل مع Server Components لتحقيق أداء فعال وهو متوافق تمامًا مع Turbopack.

باستخدام Intlayer، يمكنك:

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

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

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

Step 1: Install Dependencies

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

bash

1npm install intlayer next-intlayer

bash

1yarn add intlayer next-intlayer

bash

1pnpm add intlayer next-intlayer

Step 2: Configure Your Project

أنشئ ملف تكوين لضبط اللغات في تطبيقك:

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ENGLISH,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // اللغات الأخرى الخاصة بك
12    ],
13    defaultLocale: Locales.ENGLISH,
14  },
15};
16
17export default config;

لرؤية جميع المعلمات المتاحة، ارجع إلى وثائق إعداد التكوين هنا.

Step 3: Integrate Intlayer in Your Next.js Configuration

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

typescript

1// next.config.mjs
2import { withIntlayer } from "next-intlayer/server";
3
4/** @type {import('next').NextConfig} */
5const nextConfig = {};
6
7export default withIntlayer(nextConfig);

Step 4: Configure Middleware for Locale Detection

قم بإعداد Middleware لاكتشاف اللغة المفضلة للمستخدم:

typescript

1// src/middleware.ts
2export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
3
4export const config = {
5  matcher: "/((?!api|static|.*\\..*|_next).*)",
6};

Step 5: Define Dynamic Locale Routes

قم بتنفيذ توجيه ديناميكي للمحتوى المحلي:

قم بتغيير src/app/page.ts إلى src/app/[locale]/page.ts

ثم، قم بتنفيذ دالة generateStaticParams في تخطيط تطبيقك.

tsx

1// src/app/layout.tsx
2
3import type { ReactNode } from "react";
4import "./globals.css";
5
6export { generateStaticParams } from "next-intlayer"; // سطر للإدراج
7
8const RootLayout = ({
9  children,
10}: Readonly<{
11  children: ReactNode;
12}>) => children;
13
14export default RootLayout;

ثم أضف تخطيطًا جديدًا في دليل [locale] الخاص بك:

tsx

1// src/app/[locale]/layout.tsx
2
3import { type NextLayoutIntlayer } from "next-intlayer";
4import { Inter } from "next/font/google";
5import { getHTMLTextDir } from "intlayer";
6
7const inter = Inter({ subsets: ["latin"] });
8
9const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
10  const { locale } = await params;
11  return (
12    <html lang={locale} dir={getHTMLTextDir(locale)}>
13      <body className={inter.className}>{children}</body>
14    </html>
15  );
16};
17
18export default LocaleLayout;

Step 6: Declare Your Content

قم بإنشاء وإدارة قواميس المحتوى الخاصة بك:

tsx

1// src/app/[locale]/page.content.ts
2import { t, type DeclarationContent } from "intlayer";
3
4const pageContent = {
5  key: "page",
6  content: {
7    getStarted: {
8      main: t({
9        en: "Get started by editing",
10        fr: "Commencez par éditer",
11        es: "Comience por editar",
12      }),
13      pageLink: "src/app/page.tsx",
14    },
15  },
16} satisfies DeclarationContent;
17
18export default pageContent;

شاهد كيفية إعلان ملفات إعلان Intlayer الخاصة بك.

Step 7: Utilize Content in Your Code

الوصول إلى قواميس المحتوى في جميع أنحاء تطبيقك:

tsx

1// src/app/[locale]/page.ts
2
3import { ClientComponentExample } from "@component/ClientComponentExample";
4import { LocaleSwitcher } from "@component/LangSwitcherDropDown";
5import { NestedServerComponentExample } from "@component/NestedServerComponentExample";
6import { ServerComponentExample } from "@component/ServerComponentExample";
7import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
8import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
9
10const PageContent = () => {
11  const { title, content } = useIntlayer("page");
12
13  return (
14    <>
15      <p>{content.getStarted.main}</p>
16      <code>{content.getStarted.pageLink}</code>
17    </>
18  );
19};
20
21const Page: NextPageIntlayer = async ({ params }) => {
22  const { locale } = await params;
23
24  return (
25    <>
26      {/**
27       *   IntlayerServerProvider يُستخدم لتوفير اللغة للأطفال على الخادم
28       *   لا يعمل إذا تم تعيينه في التخطيط
29       */}
30      <IntlayerServerProvider locale={locale}>
31        <PageContent />
32        <ServerComponentExample />
33      </IntlayerServerProvider>
34      {/**
35       *   IntlayerClientProvider يُستخدم لتوفير اللغة للأطفال على العميل
36       *   يمكن تعيينه في أي مكون رئيسي، بما في ذلك التخطيط
37       */}
38      <IntlayerClientProvider locale={locale}>
39        <ClientComponentExample />
40      </IntlayerClientProvider>
41    </>
42  );
43};
44
45export default Page;

tsx

1// src/components/ClientComponentExample.tsx
2
3"use client";
4
5import { useIntlayer } from "next-intlayer";
6
7export const ClientComponentExample = () => {
8  const content = useIntlayer("client-component-example"); // إنشاء إعلان محتوى ذات صلة
9
10  return (
11    <div>
12      <h2>{content.title} </h2>
13      <p>{content.content}</p>
14    </div>
15  );
16};

tsx

1// src/components/ServerComponentExample.tsx
2
3import { useIntlayer } from "next-intlayer/server";
4
5export const ServerComponentExample = () => {
6  const content = useIntlayer("server-component-example"); // إنشاء إعلان محتوى ذات صلة
7
8  return (
9    <div>
10      <h2>{content.title} </h2>
11      <p>{content.content}</p>
12    </div>
13  );
14};

ملاحظة: إذا كنت ترغب في استخدام المحتوى الخاص بك في خاصية string، مثل alt أو title أو href أو aria-label، يجب عليك استدعاء قيمة الدالة، مثل:
tsx
1<img src={content.image.src.value} alt={content.image.value} />

لمزيد من الاستخدامات التفصيلية لـ intlayer في مكون العميل أو الخادم، انظر مثال Next.js هنا.

(Optional) Step 8: Internationalization of your metadata

في حالة رغبتك في ترجمة بيانات التعريف الخاصة بك، مثل عنوان الصفحة، يمكنك استخدام دالة generateMetadata المقدمة من Next.js. داخل الدالة استخدم دالة getTranslationContent لترجمة بيانات التعريف الخاصة بك.

typescript

1// src/app/[locale]/layout.tsx أو src/app/[locale]/page.tsx
2
3import {
4  type IConfigLocales,
5  getTranslationContent,
6  getMultilingualUrls,
7} from "intlayer";
8import type { Metadata } from "next";
9import type { LocalParams } from "next-intlayer";
10
11export const generateMetadata = ({
12  params: { locale },
13}: LocalParams): Metadata => {
14  const t = <T>(content: IConfigLocales<T>) =>
15    getTranslationContent(content, locale);
16
17  /**
18   * ينشئ كائنًا يحتوي على جميع الروابط لكل لغة.
19   *
20   * مثال:
21   * ```ts
22   *  getMultilingualUrls('/about');
23   *
24   *  // يعيد
25   *  // {
26   *  //   en: '/about',
27   *  //   fr: '/fr/about',
28   *  //   es: '/es/about',
29   *  // }
30   * ```
31   */
32  const multilingualUrls = getMultilingualUrls("/");
33
34  return {
35    title: t<string>({
36      en: "My title",
37      fr: "Mon titre",
38      es: "Mi título",
39    }),
40    description: t({
41      en: "My description",
42      fr: "Ma description",
43      es: "Mi descripción",
44    }),
45    alternates: {
46      canonical: url,
47      languages: { ...multilingualUrls, "x-default": "/" },
48    },
49    openGraph: {
50      url: multilingualUrls[locale],
51    },
52  };
53};
54
55// ... بقية الكود

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

(Optional) Step 9: Internationalization of your sitemap.xml and robots.txt

لترجمة sitemap.xml و robots.txt الخاصة بك، يمكنك استخدام دالة getMultilingualUrls المقدمة من Intlayer. تتيح لك هذه الدالة إنشاء روابط متعددة اللغات لخريطة موقعك.

tsx

1// src/app/sitemap.ts
2
3import { getMultilingualUrls } from "intlayer";
4import type { MetadataRoute } from "next";
5
6const sitemap = (): MetadataRoute.Sitemap => [
7  {
8    url: "https://example.com",
9    alternates: {
10      languages: getMultilingualUrls("https://example.com"),
11    },
12  },
13  {
14    url: "https://example.com/login",
15    alternates: {
16      languages: getMultilingualUrls("https://example.com/login"),
17    },
18  },
19  {
20    url: "https://example.com/register",
21    alternates: {
22      languages: getMultilingualUrls("https://example.com/register"),
23    },
24  },
25];
26
27export default sitemap;

tsx

1// src/app/robots.ts
2import type { MetadataRoute } from "next";
3import { getMultilingualUrls } from "intlayer";
4
5const getAllMultilingualUrls = (urls: string[]) =>
6  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
7
8const robots = (): MetadataRoute.Robots => ({
9  rules: {
10    userAgent: "*",
11    allow: ["/"],
12    disallow: getAllMultilingualUrls(["/login", "/register"]),
13  },
14  host: "https://example.com",
15  sitemap: `https://example.com/sitemap.xml`,
16});
17
18export default robots;

تعرف على المزيد حول تحسين خريطة الموقع في الوثائق الرسمية لـ Next.js. تعرف على المزيد حول تحسين robots.txt في الوثائق الرسمية لـ Next.js.

(Optional) Step 10: Change the language of your content

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

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "next-intlayer";
3
4const MyComponent = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.English)}>تغيير اللغة</button>
9  );
10};

Configure TypeScript

يستخدم Intlayer تحسين وحدات الموديل للاستفادة من TypeScript وجعل كودك أكثر قوة.

alt text

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

json5

1// tsconfig.json
2
3{
4  // تكوينك المخصص
5  include: [
6    "src",
7    "types", // <- تضمين الأنواع التي تم إنشاؤها تلقائيًا
8  ],
9}

Git Configuration

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

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

gitignore

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

إذا كان لديك فكرة لتحسين هذه الوثيقة، فلا تتردد في المساهمة من خلال تقديم طلب سحب على GitHub.

رابط GitHub للتوثيق

استرداد الوظيفة Next.js 14 وموجه التطبيق

Getting Started internationalizing (i18n) with Intlayer and Next.js 15 App Router

What is Intlayer?

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

Step 1: Install Dependencies

Step 2: Configure Your Project

Step 3: Integrate Intlayer in Your Next.js Configuration

Step 4: Configure Middleware for Locale Detection

Step 5: Define Dynamic Locale Routes

Step 6: Declare Your Content

Step 7: Utilize Content in Your Code

(Optional) Step 8: Internationalization of your metadata

(Optional) Step 9: Internationalization of your sitemap.xml and robots.txt

(Optional) Step 10: Change the language of your content

Configure TypeScript

Git Configuration

في هذه الصفحة