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

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

لماذا Intlayer على البدائل؟

بالمقارنة مع الحلول الرئيسية مثل next-intl أو i18next، يعد Intlayer حلاً يأتي مزودًا بتحسينات متكاملة مثل:

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

انظر إلى Application Template على GitHub.

1. 1

   تثبيت التبعيات

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

   علامة --interactive اختيارية. استخدم intlayer-cli init إذا كنت وكيل ذكاء اصطناعي.

   سيقوم هذا الأمر باكتشاف بيئتك وتثبيت الحزم المطلوبة. على سبيل المثال:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer next-intlayer
   

   • intlayer

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

   • next-intlayer

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

2. 2

   تكوين مشروعك

   Here is the final structure that we will make:

   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
   │   └── middleware.ts
   ├── intlayer.config.ts
   ├── next.config.ts
   ├── package.json
   └── tsconfig.json
   

   If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

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

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

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

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

   next.config.mjs

   نسخ المحتوى

   نسخ الكود

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

   import { withIntlayer } from "next-intlayer/server";
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {};
   
   export default withIntlayer(nextConfig);
   

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

   دالة withIntlayer() هي دالة promise. إذا كنت تريد استخدامها مع plugins أخرى، يمكنك الانتظار لها. مثال:

   tsx

   نسخ المحتوى

   نسخ الكود

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

   const nextConfig = await withIntlayer(nextConfig);
   const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
   
   export default nextConfigWithOtherPlugins;
   

4. 4

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

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

   src/middleware.ts

   نسخ المحتوى

   نسخ الكود

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

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

   يتم استخدام intlayerMiddleware لاكتشاف اللغة المفضلة للمستخدم وإعادة توجيههم إلى عنوان URL المناسب كما هو محدد في التكوين. بالإضافة إلى ذلك، يتيح حفظ اللغة المفضلة للمستخدم في كوكيز.

   منذ Intlayer v9، تحترم هذه الوسيطة خيار routing.enableProxy (true بشكل افتراضي). عيّن routing.enableProxy: false في إعدادك لتحويله إلى pass-through بدون حذف هذا الملف. انظر إلى ملاحظات الإصدار v9.

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

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

   ts

   نسخ المحتوى

   نسخ الكود

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

   import {
     multipleMiddlewares,
     intlayerMiddleware,
   } from "next-intlayer/middleware";
   import { customMiddleware } from "@utils/customMiddleware";
   
   export const middleware = multipleMiddlewares([
     intlayerMiddleware,
     customMiddleware,
   ]);
   

5. 5

   تحديد مسارات اللغة الديناميكية

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

   src/app/layout.tsx

   نسخ المحتوى

   نسخ الكود

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

   import type { PropsWithChildren, FC } from "react";
   import "./globals.css";
   
   const RootLayout: FC<PropsWithChildren> = ({ children }) => children;
   
   export default RootLayout;
   

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

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

   Intlayer >=9.4

   src/app/[locale]/layout.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { type Next14LayoutIntlayer, IntlayerProvider } from "next-intlayer";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => (
     <html lang={locale} dir={getHTMLTextDir(locale)}>
       <body className={inter.className}>
         <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
       </body>
     </html>
   );
   

   موفر IntlayerProvider واحد يغطي نصي الشجرة: فهو يزرع سياق الخادم ذو النطاق المحدد بالطلب والذي تقرأه خطافات الخادم، ويثبت موفر العميل بحيث تتلقى مكونات العميل نفس اللغة.

   src/app/[locale]/layout.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout = ({ children, params: { locale } }) => (
   
     <html lang={locale} dir={getHTMLTextDir(locale)}>
       <body className={inter.className}>
           {children}
         </body>
     </html>
   );
   
   export default LocaleLayout;
   
   

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

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

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

   src/app/[locale]/layout.tsx

   نسخ المحتوى

   نسخ الكود

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

   export { generateStaticParams } from "next-intlayer"; // السطر للإدراج
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => {
     /*... بقية الكود */
   };
   
   export default LocaleLayout;
   

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

6. 6

   إعلان المحتوى الخاص بك

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

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

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       getStarted: {
         main: t({
           ar: "ابدأ بالتعديل",
           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,md,mdx,yaml,yml}). لمزيد من التفاصيل، راجع وثائق إعلان المحتوى.

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

7. 7

   استخدام المحتوى في الكود الخاص بك

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

   Intlayer >=9.4Intlayer <9.4

   src/app/[locale]/page.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type Next14PageIntlayer } from "next-intlayer";
   import { useIntlayer } from "next-intlayer";
   
   const Page: Next14PageIntlayer = ({ params: { locale } }) => {
     const content = useIntlayer("page", locale);
   
     return (
       <>
         <p>
           {content.getStarted.main}
           <code>{content.getStarted.pageLink}</code>
         </p>
   
         <ServerComponentExample />
         <ClientComponentExample />
       </>
     );
   };
   
   export default Page;
   

   • IntlayerProvider يتم تثبيته مرة واحدة فقط، في تخطيط الإعدادات المحلية. يوفر الإعدادات المحلية لكل من مكونات الخادم والعميل، لذا لا تحتاج الصفحات إلى التفاف نفسها بعد الآن.
   • خوادم الخادم تحل الإعدادات المحلية بهذا الترتيب: الإعدادات المحلية المُمررة في موقع الاستدعاء، ثم سياق الخادم الذي تم وضعه بواسطة المزود، ثم الإعدادات المحلية المرسلة عبر الطلب (رأس x-intlayer-locale الذي تم تعيينه بواسطة وكيل Intlayer، ثم ملف تعريف الارتباط للإعدادات المحلية). هذه الخطوة الأخيرة هي ما يحافظ على صحة المحتوى على تنقل من جانب العميل يعيد تصيير جزء الصفحة فقط، حيث لا يعاد تشغيل التخطيط — ومعه المزود —.

   src/app/[locale]/page.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type Next14PageIntlayer } from "next-intlayer";
   import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
   
   const Page: Next14PageIntlayer = ({ params: { locale } }) => {
     const content = useIntlayer("page", locale);
   
     return (
       <>
         <p>
           {content.getStarted.main}
           <code>{content.getStarted.pageLink}</code>
         </p>
   
         <IntlayerServerProvider locale={locale}>
           <ServerComponentExample />
           <ClientComponentExample />
         </IntlayerServerProvider>
       </>
     );
   };
   
   export default Page;
   

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

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

   src/components/ClientComponentExample.tsx

   نسخ المحتوى

   نسخ الكود

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

   "use client";
   
   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   const ClientComponentExample: FC = () => {
     const content = useIntlayer("client-component-example"); // إنشاء إعلان محتوى ذو صلة
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   Intlayer >=9.4Intlayer <9.4

   src/components/ServerComponentExample.tsx

   نسخ المحتوى

   نسخ الكود

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

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // إنشاء إعلان محتوى ذي صلة
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };
   

   next-intlayer هو مسار الاستيراد متساوي الشكل: شرط تصدير react-server يعطي مكونات الخادم تنفيذ الإعدادات المحلية المحيطة، بينما مكونات العميل تحصل على الإعدادات المدعومة بالسياق. نفس الاستدعاء يعمل على كلا الجانبين.

   src/components/ServerComponentExample.tsx

   نسخ المحتوى

   نسخ الكود

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

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer/server";
   
   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، إلخ، يجب عليك استدعاء قيمة الوظيفة، مثل:

   tsx

   نسخ المحتوى

   نسخ الكود

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

   <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، راجع التوثيق.

8. 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 aplicación 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;
   

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

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

9. 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"),
       },
     },
     {
       url: "https://example.com/login",
       alternates: {
         languages: getMultilingualUrls("https://example.com/login"),
       },
     },
     {
       url: "https://example.com/register",
       alternates: {
         languages: getMultilingualUrls("https://example.com/register"),
       },
     },
   ];
   
   export default sitemap;
   
   import { getMultilingualUrls } from "intlayer";
   
   const sitemap = () => [
     {
       url: "https://example.com",
       alternates: {
         languages: getMultilingualUrls("https://example.com"),
       },
     },
     {
       url: "https://example.com/login",
       alternates: {
         languages: getMultilingualUrls("https://example.com/login"),
       },
     },
     {
       url: "https://example.com/register",
       alternates: {
         languages: getMultilingualUrls("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. 10

    تغيير لغة المحتوى الخاص بك

    اختياري

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

    src/components/LocaleSwitcher.tsx

    نسخ المحتوى

    نسخ الكود

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

    "use client";
    
    import {
      Locales,
      getHTMLTextDir,
      getLocaleName,
      getLocalizedUrl,
    } from "intlayer";
    import { useLocale } from "next-intlayer";
    import { type FC } from "react";
    import Link from "next/link";
    
    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)}
                hrefLang={localeItem}
                key={localeItem}
                aria-current={locale === localeItem ? "page" : undefined}
                onClick={() => setLocale(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 المتوفرة من خلال hook useLocale. هذه الدالة لن تسمح بجلب الصفحة مسبقاً. انظر إلى وثائق hook useLocale للمزيد من التفاصيل.

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

    src/components/LocaleSwitcher.tsx

    نسخ المحتوى

    نسخ الكود

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

    "use client";
    
    import { useLocale } from "next-intlayer";
    import { getLocalizedUrl } from "intlayer";
    
    // ... باقي الكود
    
    const { setLocale } = useLocale();
    
    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. 11

    إنشاء مكون رابط محلي

    اختياري

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

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

    • تحسين محركات البحث وتجربة المستخدم: تساعد عناوين 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 { forwardRef, PropsWithChildren, type ForwardedRef } from "react";
    
    /**
     * وظيفة مساعدة للتحقق مما إذا كان عنوان URL معين خارجيًا.
     * إذا بدأ عنوان URL بـ http:// أو https://، فإنه يعتبر خارجيًا.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * مكون رابط مخصص يتكيف مع خاصية href بناءً على اللغة الحالية.
     * بالنسبة للروابط الداخلية، يستخدم `getLocalizedUrl` لإضافة بادئة للعنوان باللغة (مثل /ar/about).
     * يضمن ذلك أن يظل التنقل ضمن سياق اللغة نفسها.
     */
    export const Link = forwardRef<
      HTMLAnchorElement,
      PropsWithChildren<NextLinkProps>
    >(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
      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} ref={ref} {...props}>
          {children}
        </NextLink>
      );
    });
    
    Link.displayName = "Link";
    

    كيف يعمل

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

    • استرجاع اللغة الحالية:
      يوفر الخطاف useLocale اللغة الحالية (مثل ar للعربية).

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

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

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

12. 12

    تحسين حجم البندل

    اختياري

    إذا كنت بحاجة إلى الـ locale النشط داخل Server Action (على سبيل المثال، لتوطين رسائل البريد الإلكتروني أو تشغيل منطق يعتمد على الـ locale)، استدعِ getLocale من next-intlayer/server:

    src/app/actions/getLocale.ts

    نسخ المحتوى

    نسخ الكود

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

    "use server";
    
    import { getLocale } from "next-intlayer/server";
    
    export const myServerAction = async () => {
      const locale = await getLocale();
    
      // افعل شيئًا باستخدام locale
    };
    

    تتبع دالة getLocale استراتيجية متسلسلة لتحديد لغة المستخدم:

    1. أولاً، تتحقق من رؤوس الطلب (request headers) للبحث عن قيمة لغة قد تكون تم تعيينها بواسطة middleware
    2. إذا لم يتم العثور على لغة في الرؤوس، تبحث عن لغة مخزنة في cookies
    3. إذا لم يتم العثور على cookie، تحاول الكشف عن اللغة المفضلة للمستخدم من إعدادات المتصفح الخاصة به
    4. كملاذ أخير، تعود إلى لغة التطبيق الافتراضية المعتمدة

    هذا يضمن اختيار اللغة الأنسب بناءً على السياق المتاح.

13. 13

    تحسين حجم حزمتك

    اختياري

    next-intlayer का उपयोग करते समय, डिफ़ॉल्ट रूप से प्रत्येक पृष्ठ के लिए शब्दकोश बंडल में शामिल होते हैं। बंडल आकार को अनुकूलित करने के लिए, Intlayer एक वैकल्पिक SWC प्लगइन प्रदान करता है जो मैक्रोज़ का उपयोग करके useIntlayer कॉल को बुद्धिमानी से बदलता है। यह सुनिश्चित करता है कि शब्दकोश केवल उन पृष्ठों के बंडल में शामिल हों जो वास्तव में उनका उपयोग करते हैं।

    इस अनुकूलन को सक्षम करने के लिए, @intlayer/swc पैकेज इंस्टॉल करें। एक बार इंस्टॉल हो जाने पर, next-intlayer स्वचालित रूप से प्लगइन का पता लगाएगा और उसका उपयोग करेगा:

    bash

    نسخ المحتوى

    نسخ الكود

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

    npm install @intlayer/swc --save-dev
    

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

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

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

تكوين TypeScript

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

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

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

تكوين Git

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

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

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

إضافة VS Code

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

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

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

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

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

التقدم أكثر

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

الأسئلة الشائعة