ترجم React Router v7 باستخدام Intlayer | التدويل (i18n)

يوضح هذا الدليل كيفية دمج Intlayer لتحقيق التدويل السلس في مشاريع React Router v7 مع توجيه يدعم اللغة المحلية، ودعم TypeScript، وممارسات تطوير حديثة.

يركز هذا الدليل على التوجيه من جانب العميل (frontend routing). لمعلومات حول توجيه fs-routes، يرجى الرجوع إلى دليل Intlayer مع React Router v7 File-System Routes.

Table of Contents

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

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

دليل خطوة بخطوة لإعداد Intlayer في تطبيق React Router v7

1. 1

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • react-intlayer الحزمة التي تدمج Intlayer مع تطبيق React. توفر موفري السياق وخطافات للتدويل في React.

   • vite-intlayer تتضمن إضافة Vite لدمج Intlayer مع مجمّع Vite، بالإضافة إلى وسيط للكشف عن اللغة المفضلة للمستخدم، وإدارة الكوكيز، والتعامل مع إعادة توجيه URL.

2. 2

   تكوين مشروعك

دليل خطوة بخطوة لإعداد Intlayer في تطبيق React Router v7 مع مسارات قائمة على نظام الملفات

VideoCodeتجربة

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-react-router-v7.vercel.app

Open embedded page in fullscreen

See Application Template on GitHub.

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

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH, // اللغة الافتراضية
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // اللغات المدعومة
  },
};

export default config;

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

1. 3

   دمج Intlayer في تكوين Vite الخاص بك

   أضف مكون intlayer الإضافي إلى تكوينك:

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { reactRouter } from "@react-router/dev/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [reactRouter(), intlayer()],
   });
   

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

2. 4

   تكوين مسارات React Router v7

   قم بإعداد تكوين التوجيه الخاص بك مع مسارات مدركة للغة:

   app/routes.ts

   نسخ المحتوى

   نسخ الكود

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

   import { layout, route, type RouteConfig } from "@react-router/dev/routes";
   
   export default [
     route("/:lang?", "routes/page.tsx"), // الصفحة الرئيسية المحلية
     route("/:lang?/about", "routes/about/page.tsx"), // صفحة حول المحلية
   ] satisfies RouteConfig;
   

3. 5

   إنشاء مكونات التخطيط

   قم بإعداد التخطيط الجذري والتخطيطات الخاصة باللغة:

   التخطيط الجذري

   app/root.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { getLocaleFromPath } from "intlayer";
   import { IntlayerProvider } from "react-intlayer";
   import {
     data,
     Meta,
     Scripts,
     ScrollRestoration,
     useLoaderData,
   } from "react-router";
   import type { Route } from "./+types/root";
   
   // ... Unchanged App, links and ErrorBoundary code
   
   export async function loader({ request }: Route.LoaderArgs) {
     const locale = getLocaleFromPath(request.url);
   
     if (!locale) {
       throw data("Language not supported", { status: 404 });
     }
   
     return { locale };
   }
   
   export function Layout({
     children,
   }: { children: React.ReactNode } & Route.ComponentProps) {
     const data = useLoaderData<typeof loader>();
     const { locale } = data ?? {};
   
     return (
       <html lang={locale}>
         <head>
           <meta charSet="utf-8" />
           <meta content="width=device-width, initial-scale=1" name="viewport" />
           <Meta />
           <Links />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <ScrollRestoration />
           <Scripts />
         </body>
       </html>
     );
   }
   

4. 6

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

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

   app/routes/[lang]/page.content.ts

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       title: t({
         en: "Welcome to React Router v7 + Intlayer",
         es: "Bienvenido a React Router v7 + Intlayer",
         fr: "Bienvenue sur React Router v7 + Intlayer",
       }),
       description: t({
         en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
         es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
         fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
       }),
       aboutLink: t({
         en: "تعرف علينا",
         es: "Aprender Sobre Nosotros",
         fr: "En savoir plus sur nous",
       }),
       homeLink: t({
         en: "الرئيسية",
         es: "Inicio",
         fr: "Accueil",
       }),
     },
   } satisfies Dictionary;
   
   export default pageContent;
   

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

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

5. 7

   إنشاء مكونات تدرك اللغة

   قم بإنشاء مكون LocalizedLink للتنقل المدرك للغة:

   app/components/localized-link.tsx

   نسخ المحتوى

   نسخ الكود

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

   import type { FC } from "react";
   
   import { getLocalizedUrl, type LocalesValues } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { Link, type LinkProps, type To } from "react-router";
   
   const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);
   
   // دالة لتحويل الرابط إلى رابط محلي بناءً على اللغة
   export const locacalizeTo = (to: To, locale: LocalesValues): To => {
     if (typeof to === "string") {
       if (isExternalLink(to)) {
         return to;
       }
   
       return getLocalizedUrl(to, locale);
     }
   
     if (isExternalLink(to.pathname ?? "")) {
       return to;
     }
   
     return {
       ...to,
       pathname: getLocalizedUrl(to.pathname ?? "", locale),
     };
   };
   
   // مكون رابط محلي يدعم التنقل حسب اللغة
   export const LocalizedLink: FC<LinkProps> = (props) => {
     const { locale } = useLocale();
   
     return <Link {...props} to={locacalizeTo(props.to, locale)} />;
   };
   

   في حال رغبت في التنقل إلى المسارات المحلية، يمكنك استخدام الخطاف useLocalizedNavigate:

   app/hooks/useLocalizedNavigate.ts

   نسخ المحتوى

   نسخ الكود

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

   import { useLocale } from "react-intlayer";
   import { type NavigateOptions, type To, useNavigate } from "react-router";
   
   import { locacalizeTo } from "~/components/localized-link";
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
     const { locale } = useLocale();
   
     const localizedNavigate = (to: To, options?: NavigateOptions) => {
       const localedTo = locacalizeTo(to, locale);
   
       navigate(localedTo, options);
     };
   
     return localizedNavigate;
   };
   

6. 8

   استخدام Intlayer في صفحاتك

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

   الصفحة الرئيسية المترجمة

   app/routes/page.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { getIntlayer, validatePrefix } from "intlayer";
   import { useIntlayer } from "react-intlayer";
   import { data } from "react-router";
   
   import { LocaleSwitcher } from "~/components/locale-switcher";
   
   import { Navbar } from "~/components/navbar";
   import type { Route } from "./+types/page";
   
   export const loader = ({ params }: Route.LoaderArgs) => {
     const { locale } = params;
   
     const { isValid } = validatePrefix(locale);
   
     if (!isValid) {
       throw data("Locale not supported", { status: 404 });
     }
   };
   
   export const meta: Route.MetaFunction = ({ params }) => {
     const content = getIntlayer("page", params.locale);
   
     return [
       { title: content.title },
       { content: content.description, name: "description" },
     ];
   };
   
   export default function Page() {
     const { title, description, aboutLink } = useIntlayer("page");
   
     return (
       <div>
         <h1>{title}</h1>
         <p>{description}</p>
         <nav>
           <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
         </nav>
       </div>
     );
   }
   

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

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

7. 9

   إنشاء مكون لتبديل اللغة

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

   app/components/locale-switcher.tsx

   نسخ المحتوى

   نسخ الكود

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

   import type { FC } from "react";
   
   import {
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
     getPathWithoutLocale,
     Locales,
   } from "intlayer";
   import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";
   import { Link, useLocation } from "react-router";
   
   export const LocaleSwitcher: FC = () => {
     const { localeSwitcherLabel } = useIntlayer("locale-switcher");
     const { pathname } = useLocation();
   
     const { availableLocales, locale } = useLocale();
   
     const pathWithoutLocale = getPathWithoutLocale(pathname);
   
     return (
       <ol>
         {availableLocales.map((localeItem) => (
           <li key={localeItem}>
             <Link
               aria-current={localeItem === locale ? "page" : undefined}
               aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
               onClick={() => setLocale(localeItem)}
               to={getLocalizedUrl(pathWithoutLocale, 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>
           </li>
         ))}
       </ol>
     );
   };
   

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

8. 10

   إضافة إدارة سمات HTML

   أنشئ خطافًا لإدارة سمات lang و dir في HTML:

   app/hooks/useI18nHTMLAttributes.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { getHTMLTextDir } from "intlayer";
   import { useEffect } from "react";
   import { useLocale } from "react-intlayer";
   
   export const useI18nHTMLAttributes = () => {
     const { locale } = useLocale();
   
     useEffect(() => {
       document.documentElement.lang = locale;
       document.documentElement.dir = getHTMLTextDir(locale);
     }, [locale]);
   };
   

   ثم استخدمه في مكون الجذر الخاص بك:

   app/routes/layout.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { Outlet } from "react-router";
   import { IntlayerProvider } from "react-intlayer";
   
   import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // استيراد الخطاف
   
   export default function RootLayout() {
     useI18nHTMLAttributes(); // استدعاء الخطاف
   
     return (
       <IntlayerProvider>
         <Outlet />
       </IntlayerProvider>
     );
   }
   

9. 11

   إضافة middleware

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

   لاحظ أنه لاستخدام intlayerProxy في الإنتاج، تحتاج إلى نقل حزمة vite-intlayer من devDependencies إلى dependencies.

   منذ Intlayer v9، يتم تجميع intlayerProxy() مباشرة في plugin intlayer() وتفعيله بشكل افتراضي من خلال خيار routing.enableProxy (true بشكل افتراضي). تسجيل هذه الدالة بشكل منفصل كما هو موضح أدناه أصبح اختيارياً الآن — يتم الاحتفاظ به للتوافقية العكسية والإعدادات التي تحتاج إلى التحكم في ترتيب plugin. عيّن routing.enableProxy: false للإلغاء. راجع ملاحظات الإصدار v9.

   vite.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react-swc";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       react(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 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;
    

    أمر الاستخراجمترجم Babel

    قم بتشغيل المستخرج لتحويل مكوناتك واستخراج المحتوى

    bash

    نسخ المحتوى

    نسخ الكود

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

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    قم بتحديث vite.config.ts لتضمين مكون intlayerCompiler الإضافي:

    vite.config.ts

    نسخ المحتوى

    نسخ الكود

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

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    نسخ المحتوى

    نسخ الكود

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

    npm run build # أو npm run dev
    

    ---

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types:

{
  // ... your existing configurations
  include: [
    // ... your existing includes
    ".intlayer/**/*.ts", // Include the auto-generated types
  ],
}

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore the files generated by Intlayer
.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.

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

• توثيق Intlayer
• توثيق React Router v7
• هوك useIntlayer
• هوك useLocale
• إعلان المحتوى
• التكوين

يوفر هذا الدليل الشامل كل ما تحتاجه لدمج Intlayer مع React Router v7 لتطبيق دولي بالكامل مع توجيه مدرك للغة ودعم TypeScript.