تلقي إشعارات حول الإصدارات القادمة من Intlayer
    المؤلف: AydinTheFirst
    إنشاء:2025-09-04آخر تحديث:2025-09-04

    البدء في التدويل (i18n) مع Intlayer و React Router v7

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

    ما هو Intlayer؟

    Intlayer هو مكتبة تدويل (i18n) مبتكرة ومفتوحة المصدر مصممة لتبسيط دعم تعدد اللغات في تطبيقات الويب الحديثة.

    مع Intlayer، يمكنك:

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

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

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

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

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-dev
    • intlayer

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

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

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

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

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

    intlayer.config.ts
    import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  internationalization: {    defaultLocale: Locales.ENGLISH,    locales: [Locales.ENGLISH, Locales.TURKISH],  },  middleware: {    prefixDefault: true, // دائمًا أضف بادئة اللغة الافتراضية في عناوين URL  },};export default config;

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

    الخطوة 3: تكوين مسارات React Router v7

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

    app/routes.ts
    import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [  layout("routes/layout.tsx", [    route("/", "routes/page.tsx"), // الصفحة الجذرية - يعيد التوجيه إلى اللغة    route("/:lang", "routes/[lang]/page.tsx"), // الصفحة الرئيسية المحلية    route("/:lang/about", "routes/[lang]/about/page.tsx"), // صفحة حول المحلية  ]),] satisfies RouteConfig;

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

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

    vite.config.ts
    import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [    reactRouter(),    tsconfigPaths(),    intlayer(),    intlayerMiddlewarePlugin(),  ],});

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

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

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

    تخطيط الجذر

    app/routes/layout.tsx
    // app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";export default function RootLayout() {  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

    الخطوة 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",      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",    }),    description: t({      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",      tr: "React Router v7 ve Intlayer kullanarak kolayca çok dilli uygulamalar geliştirin.",    }),    aboutLink: t({      en: "تعرف علينا",      tr: "Hakkımızda Öğrenin",    }),    homeLink: t({      en: "الرئيسية",      tr: "Ana Sayfa",    }),  },} satisfies Dictionary;export default pageContent;

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

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

    الخطوة 7: إنشاء مكونات مدركة للغة

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

    app/components/localized-link.tsx
    // app/components/localized-link.tsximport { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";import React from "react";import { Link, useLocation } from "react-router";type RouterLinkProps = React.ComponentProps<typeof Link>;export default function LocalizedLink({ to, ...props }: RouterLinkProps) {  const { locale } = useLocale();  const location = useLocation();  // دالة للتحقق مما إذا كان الرابط خارجيًا  const isExternal = (path: string) =>    /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");  if (typeof to === "string") {    if (to.startsWith("/") && !isExternal(to)) {      return <Link to={getLocalizedUrl(to, locale)} {...props} />;    }    return <Link to={to} {...props} />;  }  if (to && typeof to === "object") {    const pathname = (to as { pathname?: string }).pathname;    if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {      return (        <Link          to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}          {...props}        />      );    }    return <Link to={to} {...props} />;  }  return (    <Link      to={getLocalizedUrl(location.pathname + location.search, locale)}      {...props}    />  );}

    الخطوة 8: استخدام Intlayer في صفحاتك

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

    صفحة إعادة التوجيه الجذرية

    app/routes/page.tsx
    // app/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() {  const { locale } = useLocale();  return <Navigate replace to={locale} />;}

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

    app/routes/[lang]/page.tsx
    import { useIntlayer } from "react-intlayer";import LocalizedLink from "~/components/localized-link";export default function Page() {  const content = useIntlayer("page");  return (    <div style={{ padding: "2rem", textAlign: "center" }}>      <h1>{content.title}</h1>      <p>{content.description}</p>      <nav style={{ marginTop: "2rem" }}>        <LocalizedLink          to="/about"          style={{            display: "inline-block",            padding: "0.5rem 1rem",            backgroundColor: "#007bff",            color: "white",            textDecoration: "none",            borderRadius: "4px",          }}        >          {content.aboutLink}        </LocalizedLink>      </nav>    </div>  );}

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

    الخطوة 9: إنشاء مكون لتبديل اللغة

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

    app/components/locale-switcher.tsx
    import { getLocalizedUrl, getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";import { useLocation, useNavigate } from "react-router";export default function LocaleSwitcher() {  const { locale, availableLocales, setLocale } = useLocale();  const location = useLocation();  const navigate = useNavigate();  const handleLocaleChange = (newLocale: string) => {    const localizedUrl = getLocalizedUrl(      location.pathname + location.search,      newLocale    );    setLocale(newLocale);    navigate(localizedUrl);  };  return (    <div style={{ margin: "1rem 0" }}>      <label htmlFor="locale-select">اختر اللغة: </label>      <select        id="locale-select"        value={locale}        onChange={(e) => handleLocaleChange(e.target.value)}        style={{ padding: "0.25rem", marginLeft: "0.5rem" }}      >        {availableLocales.map((availableLocale) => (          <option key={availableLocale} value={availableLocale}>            {getLocaleName(availableLocale)}          </option>        ))}      </select>    </div>  );}

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

    الخطوة 10: إضافة إدارة خصائص HTML (اختياري)

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

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

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

    app/root.tsx
    // app/routes/layout.tsximport { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // استيراد الـ hookexport default function RootLayout() {  useI18nHTMLAttributes(); // استدعاء الـ hook  return (    <IntlayerProvider>      <Outlet />    </IntlayerProvider>  );}

    الخطوة 11: بناء وتشغيل تطبيقك

    قم ببناء قواميس المحتوى وتشغيل تطبيقك:

    bash
    # بناء قواميس Intlayernpm run intlayer:build# بدء خادم التطويرnpm run dev

    الخطوة 12: تكوين TypeScript (اختياري)

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

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

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

    تكوين Git

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

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

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

    النشر في بيئة الإنتاج

    عند نشر تطبيقك:

    1. قم ببناء تطبيقك:

      bash
      npm run build
    2. قم ببناء قواميس Intlayer:

      bash
      npm run intlayer:build
    3. نقل vite-intlayer إلى التبعيات إذا كنت تستخدم الوسيط (middleware) في الإنتاج:

      bash
      npm install vite-intlayer --save

    سيدعم تطبيقك الآن:

    • هيكلية عناوين URL: /en، /en/about، /tr، /tr/about
    • الكشف التلقائي عن اللغة بناءً على تفضيلات المتصفح
    • التوجيه المدرك للغة باستخدام React Router v7
    • دعم TypeScript مع أنواع مولدة تلقائيًا
    • التصيير على جانب الخادم مع التعامل الصحيح مع اللغة

    إضافة VS Code

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

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

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

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

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


    التقدم أكثر

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


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

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

    تاريخ الوثيقة

    الإصدار التاريخ التغييرات
    5.8.2 2025-09-4 أضيف لـ React Router v7
    تلقي إشعارات حول الإصدارات القادمة من Intlayer