إنشاء:2024-12-06آخر تحديث:2026-05-06

عرض قالب التطبيق على GitHub

هذه الصفحة لديها قالب تطبيق متاح.

عرض تطبيق العرض

هذه الصفحة ترتبط بعرض مباشر للقالب.

شاهد الفيديو التعليمي

هذه الصفحة لديها فيديو تعليمي متاح.

استخدم هذه الصفحة والموفر AI الذي تريده

ChatGPT

Claude

DeepSeek

Google AI mode Gemini

Perplexity Mistral

Grok

استخدم مساعدك المفضل للملخص واستخدم هذه الصفحة والموفر AI الذي تريده

تاريخ الإصدارات

"تحديث استخدام واجهة برمجة تطبيقات useIntlayer في Solid للوصول المباشر إلى الخصائص"
v8.9.04‏/5‏/2026
"إضافة أمر init"
v7.5.930‏/12‏/2025
"إضافة ذكر لـ `x-default` في كائن `alternates`"
v7.0.61‏/11‏/2025
"بداية السجل"
v7.0.029‏/6‏/2025

تمت ترجمة محتوى هذه الصفحة باستخدام الذكاء الاصطناعي.

اعرض آخر نسخة المحتوى الأصلي باللغة الإنكليزية

تعديل هذه الوثيقة

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

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

نسخ

نسخ الـ Markdown من المستند إلى الحافظة

ترجمة موقع Next.js 16 الخاص بك باستخدام Intlayer | التدويل (i18n)

Name: Intlayer
Author: Intlayer

www.youtube.com

شاهد قالب التطبيق على GitHub.

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

ما هو Intlayer؟

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

مع Intlayer، يمكنك:

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

يتوافق Intlayer مع Next.js 12 و 13 و 14 و 16. إذا كنت تستخدم Next.js Page Router، يمكنك الرجوع إلى هذا الدليل. توجيه اللغة (Locale routing) مفيد لـ SEO وحجم الحزمة والأداء. إذا لم تكن بحاجة إليه، يمكنك الرجوع إلى هذا الدليل. بالنسبة لـ Next.js 12 و 13 و 14 مع App Router، راجع هذا الدليل.

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

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

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

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm install intlayer next-intlayernpx intlayer init

intlayer

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

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

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

إليك الهيكل النهائي الذي سنقوم بإنشائه:

bash

نسخ الكود

نسخ الكود إلى الحافظة

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

إذا كنت لا ترغب في توجيه اللغة، يمكن استخدام intlayer كمزود / خطاف بسيط. راجع هذا الدليل لمزيد من التفاصيل.

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

intlayer.config.ts

نسخ الكود

نسخ الكود إلى الحافظة

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:

next.config.ts

نسخ الكود

نسخ الكود إلى الحافظة

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {
  /* خيارات التهيئة هنا */
};

export default withIntlayer(nextConfig);

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

دالة withIntlayer() هي دالة وعد (Promise). تسمح بتحضير قواميس intlayer قبل بدء البناء. إذا كنت ترغب في استخدامها مع مكونات إضافية أخرى، يمكنك انتظارها باستخدام await. مثال:
ts
نسخ الكود
نسخ الكود إلى الحافظة
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
إذا كنت ترغب في استخدامه بشكل متزامن، يمكنك استخدام دالة withIntlayerSync(). مثال:
ts
نسخ الكود
نسخ الكود إلى الحافظة
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

يكتشف Intlayer تلقائيًا ما إذا كان مشروعك يستخدم webpack أو Turbopack بناءً على أعلام سطر الأوامر --webpack أو --turbo أو --turbopack ، بالإضافة إلى إصدار Next.js الحالي.

منذ next>=16 ، إذا كنت تستخدم Rspack ، فيجب عليك إجبار Intlayer صراحةً على استخدام تكوين webpack عن طريق تعطيل Turbopack:
ts
نسخ الكود
نسخ الكود إلى الحافظة
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

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

قم بإزالة كل شيء من RootLayout واستبداله بالكود التالي:

src/app/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // لا يزال بإمكانك تغليف العناصر الفرعية بمزودين آخرين، مثل `next-themes`، `react-query`، `framer-motion`، إلخ.
  <>{children}</>
);

export default RootLayout;

يتيح ترك مكون RootLayout فارغًا تعيين سمات lang و dir إلى وسم <html>.

لتنفيذ التوجيه الديناميكي، قم بتوفير المسار للغة بإضافة تخطيط جديد في دليل [locale] الخاص بك:

src/app/[locale]/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerClientProvider locale={locale}>
          {children}
        </IntlayerClientProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;

يتم استخدام جزء المسار [locale] لتحديد اللغة المحلية. مثال: /en-US/about سيشير إلى en-US و /fr/about إلى fr.

في هذه المرحلة، ستواجه الخطأ: Error: Missing <html> and <body> tags in the root layout.. هذا متوقع لأن ملف /app/page.tsx لم يعد قيد الاستخدام ويمكن حذفه. بدلاً من ذلك، سيقوم جزء المسار [locale] بتنشيط صفحة /app/[locale]/page.tsx. ونتيجة لذلك، ستكون الصفحات متاحة عبر مسارات مثل /en، /fr، /es في متصفحك. لتعيين اللغة الافتراضية كصفحة الجذر، راجع إعداد proxy في الخطوة 7.

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

src/app/[locale]/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

export { generateStaticParams } from "next-intlayer"; // السطر الذي يجب إدراجه

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... بقية الكود */
};

export default LocaleLayout;

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

يعمل Intlayer مع export const dynamic = 'force-static'; لضمان بناء الصفحات مسبقًا لجميع اللغات.

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

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

src/app/[locale]/page.content.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

يمكن تعريف إعلانات المحتوى الخاصة بك في أي مكان في تطبيقك بمجرد تضمينها في دليل contentDir (افتراضيًا، ./src). ويجب أن تتطابق مع امتداد ملف إعلان المحتوى (افتراضيًا، .content.{json,ts,tsx,js,jsx,mjs,cjs}).

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

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

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

src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPageIntlayer = async ({ params }) => {
  const { locale } = await params;

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;

IntlayerClientProvider يُستخدم لتوفير اللغة للمكونات على جانب العميل. يمكن وضعه في أي مكون أبوي، بما في ذلك التخطيط (layout). ومع ذلك، يُنصح بوضعه في التخطيط لأن Next.js يشارك كود التخطيط عبر الصفحات، مما يجعله أكثر كفاءة. باستخدام IntlayerClientProvider في التخطيط، تتجنب إعادة تهيئته لكل صفحة، مما يحسن الأداء ويحافظ على سياق تعريب متسق في جميع أنحاء تطبيقك.
IntlayerServerProvider يُستخدم لتوفير اللغة لأطفال الخادم (server children). لا يمكن تعيينه في التخطيط.

لا يمكن للتخطيط والصفحة مشاركة سياق خادم مشترك لأن نظام سياق الخادم يعتمد على مخزن بيانات لكل طلب (عبر آلية React's cache)، مما يؤدي إلى إعادة إنشاء كل "سياق" لأجزاء مختلفة من التطبيق. وضع المزود في تخطيط مشترك سيكسر هذا العزل، مما يمنع الانتشار الصحيح لقيم سياق الخادم إلى مكونات الخادم الخاصة بك.

src/components/ClientComponentExample.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // إنشاء إعلان المحتوى المرتبط

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

src/components/ServerComponentExample.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // إنشاء إعلان المحتوى المرتبط

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

إذا كنت تريد استخدام المحتوى الخاص بك في خاصية من نوع string، مثل alt، title، href، aria-label، إلخ، يجب عليك استدعاء قيمة الدالة، مثل:

html

نسخ الكود

نسخ الكود إلى الحافظة

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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

إذا كان تطبيقك موجودًا بالفعل، يمكنك استخدام مترجم Intlayer، بالإضافة إلى أمر الاستخراج، لتحويل آلاف المكونات في ثانية واحدة.

(اختياري) الخطوة 7: تكوين الوكيل لاكتشاف اللغة

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

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 المناسب كما هو محدد في التكوين. بالإضافة إلى ذلك، يتيح حفظ اللغة المفضلة للمستخدم في ملف تعريف الارتباط (كوكي).

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

نسخ الكود

نسخ الكود إلى الحافظة

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

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

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

src/app/[locale]/metadata.content.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { type Dictionary, t } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una تطبيق Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;

src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * ينشئ كائن يحتوي على جميع الروابط لكل لغة.
   *
   * مثال:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // يعيد
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... بقية الكود

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

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

src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    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",
    }),
  };
};

// ... بقية الكود

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

(اختياري) الخطوة 9: تعريب ملف sitemap.xml و robots.txt الخاص بك

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

src/app/sitemap.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;

src/app/robots.ts

نسخ الكود

نسخ الكود إلى الحافظة

import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

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

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

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

src/components/LocaleSwitcher.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import type { FC } from "react";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import Link from "next/link";

export const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // سيضمن أن زر "العودة" في المتصفح يعيد التوجيه إلى الصفحة السابقة
          >
            <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. هذه الدالة لن تسمح بتحميل الصفحة مسبقًا. راجع توثيق الخطاف useLocale لمزيد من التفاصيل.

يمكنك أيضًا تعيين دالة في خيار onLocaleChange لتشغيل دالة مخصصة عند تغيير اللغة.

src/components/LocaleSwitcher.tsx

نسخ الكود

نسخ الكود إلى الحافظة

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

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

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

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

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

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

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

أدناه هو تنفيذ مكون Link محلي في TypeScript:

src/components/Link.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import type { PropsWithChildren, FC } from "react";

/**
 * وظيفة مساعدة للتحقق مما إذا كان عنوان URL المعطى خارجيًا.
 * إذا كان عنوان URL يبدأ بـ http:// أو https:// ، فإنه يعتبر خارجيًا.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * مكون Link مخصص يقوم بتكييف سمة href بناءً على اللغة الحالية.
 * بالنسبة للروابط الداخلية، فإنه يستخدم `getLocalizedUrl` لإلحاق اللغة ببادئة عنوان URL (مثل /fr/about).
 * هذا يضمن بقاء التنقل ضمن نفس سياق اللغة.
 */
export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
  href,
  children,
  ...props
}) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // إذا كان الرابط داخليًا وتم توفير href صالح، فاحصل على عنوان URL المحلي.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} {...props}>
      {children}
    </NextLink>
  );
};

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

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

لتسهيل هذه العملية، يقترح 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

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm install @intlayer/babel --save-dev

babel.config.js

نسخ الكود

نسخ الكود إلى الحافظة

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

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm run build # أو npm run dev

كيف يعمل

اكتشاف الروابط الخارجية:
تحدد الوظيفة المساعدة checkIsExternalLink ما إذا كان عنوان URL خارجيًا. تُترك الروابط الخارجية دون تغيير لأنها لا تحتاج إلى تعريب.
استرداد اللغة الحالية:
يوفر الخطاف useLocale اللغة الحالية (على سبيل المثال، fr للفرنسية).
تعريب عنوان URL:
بالنسبة للروابط الداخلية (أي غير الخارجية)، يتم استخدام getLocalizedUrl لإلحاق اللغة الحالية ببادئة عنوان URL تلقائيًا. هذا يعني أنه إذا كان مستخدمك يتحدث الفرنسية، فإن تمرير /about كـ href سيحوله إلى /fr/about.
إرجاع الرابط:
يعيد المكون عنصر <a> مع عنوان URL المحلي، مما يضمن أن التنقل يتوافق مع اللغة.

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

تحسين الحزمة

Next.js 14 وموجه التطبيق

إنشاء:2024-12-06آخر تحديث:2026-05-06

عرض قالب التطبيق على GitHub

هذه الصفحة لديها قالب تطبيق متاح.

عرض تطبيق العرض

هذه الصفحة ترتبط بعرض مباشر للقالب.

شاهد الفيديو التعليمي

هذه الصفحة لديها فيديو تعليمي متاح.

استخدم هذه الصفحة والموفر AI الذي تريده

ChatGPT

Claude

DeepSeek

Google AI mode Gemini

Perplexity Mistral

Grok

استخدم مساعدك المفضل للملخص واستخدم هذه الصفحة والموفر AI الذي تريده

تاريخ الإصدارات

"تحديث استخدام واجهة برمجة تطبيقات useIntlayer في Solid للوصول المباشر إلى الخصائص"
v8.9.04‏/5‏/2026
"إضافة أمر init"
v7.5.930‏/12‏/2025
"إضافة ذكر لـ `x-default` في كائن `alternates`"
v7.0.61‏/11‏/2025
"بداية السجل"
v7.0.029‏/6‏/2025

تمت ترجمة محتوى هذه الصفحة باستخدام الذكاء الاصطناعي.

اعرض آخر نسخة المحتوى الأصلي باللغة الإنكليزية

تعديل هذه الوثيقة

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

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

نسخ

نسخ الـ Markdown من المستند إلى الحافظة

ترجمة موقع Next.js 16 الخاص بك باستخدام Intlayer | التدويل (i18n)

www.youtube.com

شاهد قالب التطبيق على GitHub.

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

ما هو Intlayer؟

مع Intlayer، يمكنك:

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

يتوافق Intlayer مع Next.js 12 و 13 و 14 و 16. إذا كنت تستخدم Next.js Page Router، يمكنك الرجوع إلى هذا الدليل. توجيه اللغة (Locale routing) مفيد لـ SEO وحجم الحزمة والأداء. إذا لم تكن بحاجة إليه، يمكنك الرجوع إلى هذا الدليل. بالنسبة لـ Next.js 12 و 13 و 14 مع App Router، راجع هذا الدليل.

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

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

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

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm install intlayer next-intlayernpx intlayer init

npm install intlayer next-intlayernpx intlayer init

intlayer

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

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

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

إليك الهيكل النهائي الذي سنقوم بإنشائه:

bash

نسخ الكود

نسخ الكود إلى الحافظة

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Root layout for style and global providers│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

إذا كنت لا ترغب في توجيه اللغة، يمكن استخدام intlayer كمزود / خطاف بسيط. راجع هذا الدليل لمزيد من التفاصيل.

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

intlayer.config.ts

نسخ الكود

نسخ الكود إلى الحافظة

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:

next.config.ts

نسخ الكود

نسخ الكود إلى الحافظة

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {
  /* خيارات التهيئة هنا */
};

export default withIntlayer(nextConfig);

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

دالة withIntlayer() هي دالة وعد (Promise). تسمح بتحضير قواميس intlayer قبل بدء البناء. إذا كنت ترغب في استخدامها مع مكونات إضافية أخرى، يمكنك انتظارها باستخدام await. مثال:
ts
نسخ الكود
نسخ الكود إلى الحافظة
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
إذا كنت ترغب في استخدامه بشكل متزامن، يمكنك استخدام دالة withIntlayerSync(). مثال:
ts
نسخ الكود
نسخ الكود إلى الحافظة
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;
const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

يكتشف Intlayer تلقائيًا ما إذا كان مشروعك يستخدم webpack أو Turbopack بناءً على أعلام سطر الأوامر --webpack أو --turbo أو --turbopack ، بالإضافة إلى إصدار Next.js الحالي.

منذ next>=16 ، إذا كنت تستخدم Rspack ، فيجب عليك إجبار Intlayer صراحةً على استخدام تكوين webpack عن طريق تعطيل Turbopack:
ts
نسخ الكود
نسخ الكود إلى الحافظة
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

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

قم بإزالة كل شيء من RootLayout واستبداله بالكود التالي:

src/app/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // لا يزال بإمكانك تغليف العناصر الفرعية بمزودين آخرين، مثل `next-themes`، `react-query`، `framer-motion`، إلخ.
  <>{children}</>
);

export default RootLayout;

يتيح ترك مكون RootLayout فارغًا تعيين سمات lang و dir إلى وسم <html>.

لتنفيذ التوجيه الديناميكي، قم بتوفير المسار للغة بإضافة تخطيط جديد في دليل [locale] الخاص بك:

src/app/[locale]/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerClientProvider locale={locale}>
          {children}
        </IntlayerClientProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;

يتم استخدام جزء المسار [locale] لتحديد اللغة المحلية. مثال: /en-US/about سيشير إلى en-US و /fr/about إلى fr.

في هذه المرحلة، ستواجه الخطأ: Error: Missing <html> and <body> tags in the root layout.. هذا متوقع لأن ملف /app/page.tsx لم يعد قيد الاستخدام ويمكن حذفه. بدلاً من ذلك، سيقوم جزء المسار [locale] بتنشيط صفحة /app/[locale]/page.tsx. ونتيجة لذلك، ستكون الصفحات متاحة عبر مسارات مثل /en، /fr، /es في متصفحك. لتعيين اللغة الافتراضية كصفحة الجذر، راجع إعداد proxy في الخطوة 7.

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

src/app/[locale]/layout.tsx

نسخ الكود

نسخ الكود إلى الحافظة

export { generateStaticParams } from "next-intlayer"; // السطر الذي يجب إدراجه

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... بقية الكود */
};

export default LocaleLayout;

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

يعمل Intlayer مع export const dynamic = 'force-static'; لضمان بناء الصفحات مسبقًا لجميع اللغات.

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

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

src/app/[locale]/page.content.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

يمكن تعريف إعلانات المحتوى الخاصة بك في أي مكان في تطبيقك بمجرد تضمينها في دليل contentDir (افتراضيًا، ./src). ويجب أن تتطابق مع امتداد ملف إعلان المحتوى (افتراضيًا، .content.{json,ts,tsx,js,jsx,mjs,cjs}).

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

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

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

src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPageIntlayer = async ({ params }) => {
  const { locale } = await params;

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;

IntlayerClientProvider يُستخدم لتوفير اللغة للمكونات على جانب العميل. يمكن وضعه في أي مكون أبوي، بما في ذلك التخطيط (layout). ومع ذلك، يُنصح بوضعه في التخطيط لأن Next.js يشارك كود التخطيط عبر الصفحات، مما يجعله أكثر كفاءة. باستخدام IntlayerClientProvider في التخطيط، تتجنب إعادة تهيئته لكل صفحة، مما يحسن الأداء ويحافظ على سياق تعريب متسق في جميع أنحاء تطبيقك.
IntlayerServerProvider يُستخدم لتوفير اللغة لأطفال الخادم (server children). لا يمكن تعيينه في التخطيط.

لا يمكن للتخطيط والصفحة مشاركة سياق خادم مشترك لأن نظام سياق الخادم يعتمد على مخزن بيانات لكل طلب (عبر آلية React's cache)، مما يؤدي إلى إعادة إنشاء كل "سياق" لأجزاء مختلفة من التطبيق. وضع المزود في تخطيط مشترك سيكسر هذا العزل، مما يمنع الانتشار الصحيح لقيم سياق الخادم إلى مكونات الخادم الخاصة بك.

src/components/ClientComponentExample.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // إنشاء إعلان المحتوى المرتبط

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

src/components/ServerComponentExample.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // إنشاء إعلان المحتوى المرتبط

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

إذا كنت تريد استخدام المحتوى الخاص بك في خاصية من نوع string، مثل alt، title، href، aria-label، إلخ، يجب عليك استدعاء قيمة الدالة، مثل:

html

نسخ الكود

نسخ الكود إلى الحافظة

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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

إذا كان تطبيقك موجودًا بالفعل، يمكنك استخدام مترجم Intlayer، بالإضافة إلى أمر الاستخراج، لتحويل آلاف المكونات في ثانية واحدة.

(اختياري) الخطوة 7: تكوين الوكيل لاكتشاف اللغة

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

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 المناسب كما هو محدد في التكوين. بالإضافة إلى ذلك، يتيح حفظ اللغة المفضلة للمستخدم في ملف تعريف الارتباط (كوكي).

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

نسخ الكود

نسخ الكود إلى الحافظة

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

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

src/app/[locale]/metadata.content.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { type Dictionary, t } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una تطبيق Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;

src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * ينشئ كائن يحتوي على جميع الروابط لكل لغة.
   *
   * مثال:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // يعيد
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... بقية الكود

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

src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

نسخ الكود

نسخ الكود إلى الحافظة

import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    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",
    }),
  };
};

// ... بقية الكود

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

(اختياري) الخطوة 9: تعريب ملف sitemap.xml و robots.txt الخاص بك

src/app/sitemap.ts

نسخ الكود

نسخ الكود إلى الحافظة

import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;

src/app/robots.ts

نسخ الكود

نسخ الكود إلى الحافظة

import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

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

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

src/components/LocaleSwitcher.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import type { FC } from "react";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import Link from "next/link";

export const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // سيضمن أن زر "العودة" في المتصفح يعيد التوجيه إلى الصفحة السابقة
          >
            <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. هذه الدالة لن تسمح بتحميل الصفحة مسبقًا. راجع توثيق الخطاف useLocale لمزيد من التفاصيل.

يمكنك أيضًا تعيين دالة في خيار onLocaleChange لتشغيل دالة مخصصة عند تغيير اللغة.

src/components/LocaleSwitcher.tsx

نسخ الكود

نسخ الكود إلى الحافظة

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

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

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

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

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

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

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

أدناه هو تنفيذ مكون Link محلي في TypeScript:

src/components/Link.tsx

نسخ الكود

نسخ الكود إلى الحافظة

"use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import type { PropsWithChildren, FC } from "react";

/**
 * وظيفة مساعدة للتحقق مما إذا كان عنوان URL المعطى خارجيًا.
 * إذا كان عنوان URL يبدأ بـ http:// أو https:// ، فإنه يعتبر خارجيًا.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * مكون Link مخصص يقوم بتكييف سمة href بناءً على اللغة الحالية.
 * بالنسبة للروابط الداخلية، فإنه يستخدم `getLocalizedUrl` لإلحاق اللغة ببادئة عنوان URL (مثل /fr/about).
 * هذا يضمن بقاء التنقل ضمن نفس سياق اللغة.
 */
export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
  href,
  children,
  ...props
}) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // إذا كان الرابط داخليًا وتم توفير href صالح، فاحصل على عنوان URL المحلي.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} {...props}>
      {children}
    </NextLink>
  );
};

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

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

لتسهيل هذه العملية، يقترح 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

npx intlayer extract

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm install @intlayer/babel --save-dev

npm install @intlayer/babel --save-dev

babel.config.js

نسخ الكود

نسخ الكود إلى الحافظة

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

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

bash

نسخ الكود

نسخ الكود إلى الحافظة

npm run build # أو npm run dev

npm run build # أو npm run dev

كيف يعمل

اكتشاف الروابط الخارجية:
تحدد الوظيفة المساعدة checkIsExternalLink ما إذا كان عنوان URL خارجيًا. تُترك الروابط الخارجية دون تغيير لأنها لا تحتاج إلى تعريب.
استرداد اللغة الحالية:
يوفر الخطاف useLocale اللغة الحالية (على سبيل المثال، fr للفرنسية).
تعريب عنوان URL:
بالنسبة للروابط الداخلية (أي غير الخارجية)، يتم استخدام getLocalizedUrl لإلحاق اللغة الحالية ببادئة عنوان URL تلقائيًا. هذا يعني أنه إذا كان مستخدمك يتحدث الفرنسية، فإن تمرير /about كـ href سيحوله إلى /fr/about.
إرجاع الرابط:
يعيد المكون عنصر <a> مع عنوان URL المحلي، مما يضمن أن التنقل يتوافق مع اللغة.

تحسين الحزمة

Next.js 14 وموجه التطبيق