Documentation

بيئة

Intlayer مع Vite و React

Getting Started Internationalizing (i18n) with Intlayer and Vite and React

What is Intlayer?

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

مع Intlayer، يمكنك:

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

Step-by-Step Guide to Set Up Intlayer in a Vite and React Application

Step 1: Install Dependencies

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

bash

1npm install intlayer react-intlayer

bash

1yarn add intlayer react-intlayer

bash

1pnpm add intlayer react-intlayer

Step 2: Configuration of your project

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

typescript

1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6  internationalization: {
7    locales: [
8      Locales.ARABIC,
9      Locales.FRENCH,
10      Locales.SPANISH,
11      // Your other locales
12    ],
13    defaultLocale: Locales.ARABIC,
14  },
15};
16
17export default config;

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

Step 3: Integrate Intlayer in Your Vite Configuration

أضف المكون الإضافي Intlayer إلى تكوينك.

typescript

1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7  plugins: [react(), intLayerPlugin()],
8});

Step 4: Declare Your Content

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

tsx

1// src/app.content.tsx
2import { t, type DeclarationContent } from "intlayer";
3import { type ReactNode } from "react";
4
5const appContent = {
6  key: "app",
7  content: {
8    viteLogo: t({
9      ar: "شعار Vite",
10      fr: "Logo Vite",
11      es: "Logo Vite",
12    }),
13    reactLogo: t({
14      ar: "شعار React",
15      fr: "Logo React",
16      es: "Logo React",
17    }),
18
19    title: "Vite + React",
20
21    count: t({
22      ar: "عدد هو ",
23      fr: "le compte est ",
24      es: "el recuento es ",
25    }),
26
27    edit: t<ReactNode>({
28      // تذكر أن تستورد React إذا كنت تستخدم عقدة React في محتواك
29      ar: (
30        <>
31          قم بتحرير <code>src/App.tsx</code> واحفظ لاختبار HMR
32        </>
33      ),
34      fr: (
35        <>
36          Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR
37        </>
38      ),
39      es: (
40        <>
41          Edita <code>src/App.tsx</code> y guarda para probar HMR
42        </>
43      ),
44    }),
45
46    readTheDocs: t({
47      ar: "انقر على شعارات Vite و React لمعرفة المزيد",
48      fr: "Cliquez sur les logos Vite et React pour en savoir plus",
49      es: "Haga clic en los logotipos de Vite y React para obtener más información",
50    }),
51  },
52} satisfies DeclarationContent;
53
54export default appContent;

ملاحظة: إذا كان ملف المحتوى الخاص بك يتضمن كود TSX، يجب أن تأخذ في الاعتبار استيراد import React from "react"; في ملف المحتوى الخاص بك.

رؤية كيفية إعلان ملفات إعلان Intlayer.

Step 5: Utilize Intlayer in Your Code

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

tsx

1import { useState } from "react";
2import reactLogo from "./assets/react.svg";
3import viteLogo from "/vite.svg";
4import "./App.css";
5import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
6import { IntlayerProvider, useIntlayer } from "react-intlayer";
7
8function AppContent() {
9  const [count, setCount] = useState(0);
10  const content = useIntlayer("app");
11
12  return (
13    <>
14      <div>
15        <a href="https://vitejs.dev" target="_blank">
16          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
17        </a>
18        <a href="https://react.dev" target="_blank">
19          <img
20            src={reactLogo}
21            className="logo react"
22            alt={content.reactLogo.value}
23          />
24        </a>
25      </div>
26      <h1>{content.title}</h1>
27      <div className="card">
28        <button onClick={() => setCount((count) => count + 1)}>
29          {content.count}
30          {count}
31        </button>
32        <p>{content.edit}</p>
33      </div>
34      <p className="read-the-docs">{content.readTheDocs}</p>
35      <div className="absolute bottom-5 right-5 z-50">
36        <LocaleSwitcher />
37      </div>
38    </>
39  );
40}
41
42function App() {
43  return (
44    <IntlayerProvider>
45      <AppContent />
46    </IntlayerProvider>
47  );
48}
49
50export default App;

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

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

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

tsx

1import { Locales } from "intlayer";
2import { useLocale } from "react-intlayer";
3
4const LocaleSwitcher = () => {
5  const { setLocale } = useLocale();
6
7  return (
8    <button onClick={() => setLocale(Locales.Arabic)}>
9      تغيير اللغة إلى العربية
10    </button>
11  );
12};

(Optional) Step 7: Add localized Routing to your application

الغرض من هذه الخطوة هو إنشاء مسارات فريدة لكل لغة. هذا مفيد لتحسين محركات البحث وعناوين URL المناسبة لتحسين محركات البحث. مثال:

tsx

1// /dashboard
2// /es/dashboard
3// /fr/dashboard

بشكل افتراضي، لا تكون المسارات مسبوقة للغة الافتراضية. إذا كنت ترغب في وضع بادئة للغة الافتراضية، يمكنك تعيين خيار middleware.prefixDefault إلى true في تكوينك. راجع وثائق التكوين لمزيد من المعلومات.

لإضافة التوجيه المحلي إلى تطبيقك، يمكنك إنشاء مكون LocaleRouter الذي يغلف مسارات تطبيقك ويدير التوجيه القائم على اللغة. إليك مثال باستخدام React Router:

tsx

1// استيراد الاعتماديات والوظائف الضرورية
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // وظائف وأصناف مساعدة من 'intlayer'
3import { FC, PropsWithChildren } from "react"; // أنواع React للمكونات الوظيفية والخصائص
4import { IntlayerProvider } from "react-intlayer"; // مزود لسياق التدويل
5import {
6  BrowserRouter,
7  Routes,
8  Route,
9  useParams,
10  Navigate,
11  useLocation,
12} from "react-router-dom"; // مكونات التوجيه لإدارة التنقل
13
14// تفكيك التكوين من Intlayer
15const { internationalization, middleware } = getConfiguration();
16const { locales, defaultLocale } = internationalization;
17
18/**
19 * مكون يدير التدويل ويغلف الأطفال بسياق اللغة المناسب.
20 * يدير الكشف عن اللغة بناءً على URL والتحقق.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23  const path = useLocation().pathname; // الحصول على مسار URL الحالي
24  const { locale } = useParams<{ locale: Locales }>(); // استخراج معلمة اللغة من URL
25
26  // تحديد اللغة الحالية، مع التراجع إلى الافتراضي إذا لم يتم توفيرها
27  const currentLocale = locale ?? defaultLocale;
28
29  // إزالة بادئة اللغة من المسار لبناء مسار أساسي
30  const pathWithoutLocale = getPathWithoutLocale(
31    path // مسار URL الحالي
32  );
33
34  /**
35   * إذا كانت middleware.prefixDefault صحيحة، يجب أن تكون اللغة الافتراضية دائمًا مسبوقة.
36   */
37  if (middleware.prefixDefault) {
38    // تحقق من اللغة
39    if (!locale || !locales.includes(locale)) {
40      // إعادة التوجيه إلى اللغة الافتراضية مع المسار المحدث
41      return (
42        <Navigate
43          to={`/${defaultLocale}/${pathWithoutLocale}`}
44          replace // استبدال الإدخال الحالي في التاريخ بالإدخال الجديد
45        />
46      );
47    }
48
49    // لف الأطفال بمزود Intlayer وتعيين اللغة الحالية
50    return (
51      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52    );
53  } else {
54    /**
55     * عندما middleware.prefixDefault تكون خاطئة، لا تكون اللغة الافتراضية مسبوقة.
56     * تأكد من أن اللغة الحالية صالحة وليست اللغة الافتراضية.
57     */
58    if (
59      currentLocale.toString() !== defaultLocale.toString() &&
60      !locales
61        .filter(
62          (locale) => locale.toString() !== defaultLocale.toString() // استبعاد اللغة الافتراضية
63        )
64        .includes(currentLocale) // تحقق مما إذا كانت اللغة الحالية في قائمة اللغات الصالحة
65    ) {
66      // إعادة التوجيه إلى المسار بدون بادئة اللغة
67      return <Navigate to={pathWithoutLocale} replace />;
68    }
69
70    // لف الأطفال بمزود Intlayer وتعيين اللغة الحالية
71    return (
72      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73    );
74  }
75};
76
77/**
78 * مكون توجيه يضبط المسارات الخاصة باللغة.
79 * يستخدم React Router لإدارة التنقل ورسم المكونات المحلية.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82  <BrowserRouter>
83    <Routes>
84      <Route
85        // نمط المسار لالتقاط اللغة (مثل /ar/, /fr/) ومطابقة جميع المسارات اللاحقة
86        path="/:locale/*"
87        element={<AppLocalized>{children}</AppLocalized>} // يحاط الأطفال بإدارة اللغة
88      />
89
90      {
91        // إذا كانت عملية وضع بادئة على اللغة الافتراضية معطلة، ارسم الأطفال مباشرة على المسار الجذري
92        !middleware.prefixDefault && (
93          <Route
94            path="*"
95            element={<AppLocalized>{children}</AppLocalized>} // يحاط الأطفال بإدارة اللغة
96          />
97        )
98      }
99    </Routes>
100  </BrowserRouter>
101);

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

ts

1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin, intLayerMiddlewarePlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7  plugins: [react(), intLayerPlugin(), intLayerMiddlewarePlugin()],
8});

(Optional) Step 8: Change the URL when the locale changes

لتغيير عنوان URL عندما تتغير اللغة، يمكنك استخدام خاصية onLocaleChange التي يوفرها الخطاف useLocale. بالتوازي، يمكنك استخدام الخطافات useLocation و useNavigate من react-router-dom لتحديث مسار URL.

tsx

1import { Locales, getLocalizedUrl } from "intlayer";
2import { useLocale } from "react-intlayer";
3import { useLocation, useNavigate } from "react-router-dom";
4
5const LocaleSwitcher = () => {
6  const location = useLocation(); // الحصول على مسار URL الحالي. مثال: /fr/about
7  const navigate = useNavigate();
8
9  const changeUrl = (locale: Locales) => {
10    // بناء عنوان URL مع اللغة المحدثة
11    // مثال: /es/about مع تعيين اللغة إلى الإسبانية
12    const pathWithLocale = getLocalizedUrl(location.pathname, locale);
13
14    // تحديث مسار URL
15    navigate(pathWithLocale);
16  };
17
18  const { setLocale } = useLocale({
19    onLocaleChange: changeUrl,
20  });
21
22  return (
23    <button onClick={() => setLocale(Locales.Arabic)}>
24      تغيير اللغة إلى العربية
25    </button>
26  );
27};

Configure TypeScript

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

alt text

تأكد من أن تكوين TypeScript الخاص بك يتضمن الأنواع الذاتية التوليد.

json5

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

Git Configuration

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

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

gitignore

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

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

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

Intlayer مع React CRA Intlayer مع Express

Getting Started Internationalizing (i18n) with Intlayer and Vite and React

What is Intlayer?

Step-by-Step Guide to Set Up Intlayer in a Vite and React Application

Step 1: Install Dependencies

Step 2: Configuration of your project

Step 3: Integrate Intlayer in Your Vite Configuration

Step 4: Declare Your Content

Step 5: Utilize Intlayer in Your Code

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

(Optional) Step 7: Add localized Routing to your application

(Optional) Step 8: Change the URL when the locale changes

Configure TypeScript

Git Configuration

في هذه الصفحة