البدء في الدولنة (i18n) باستخدام Intlayer و React Create App
ما هو Intlayer؟
Intlayer هي مكتبة مبتكرة ومفتوحة المصدر للدولنة (i18n) مصممة لتبسيط دعم تعدد اللغات في تطبيقات الويب الحديثة.
باستخدام Intlayer، يمكنك:
- إدارة الترجمات بسهولة باستخدام قواميس إعلانية على مستوى المكونات.
- تخصيص بيانات التعريف، والمسارات، والمحتوى ديناميكيًا.
- ضمان دعم TypeScript مع أنواع مولدة تلقائيًا، مما يحسن من إكمال التعليمات البرمجية واكتشاف الأخطاء.
- الاستفادة من ميزات متقدمة، مثل الكشف عن اللغة الديناميكي والتبديل بينها.
دليل خطوة بخطوة لإعداد Intlayer في تطبيق React
الخطوة 1: تثبيت التبعيات
قم بتثبيت الحزم اللازمة باستخدام npm:
1npm install intlayer react-intlayer1yarn add intlayer react-intlayer1pnpm add intlayer react-intlayerالخطوة 2: تكوين مشروعك
قم بإنشاء ملف تكوين لتحديد لغات تطبيقك:
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 // لغات أخرى
12 ],
13 defaultLocale: Locales.ARABIC,
14 },
15};
16
17export default config;لرؤية جميع المعلمات المتاحة، راجع وثائق التكوين هنا.
الخطوة 3: دمج Intlayer في تكوين CRA الخاص بك
قم بتغيير النصوص البرمجية الخاصة بك لاستخدام react-intlayer
1 "scripts": {
2 "build": "react-intlayer build",
3 "start": "react-intlayer start",
4 "transpile": "intlayer build"
5 },ملاحظة: تعتمد نصوص react-intlayer على craco. يمكنك أيضًا تنفيذ إعدادك الخاص بناءً على مكون intlayer craco. انظر المثال هنا.
الخطوة 4: إعلان محتواك
قم بإنشاء وإدارة قواميس المحتوى الخاصة بك:
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 getStarted: t<ReactNode>({
9 en: (
10 <>
11 Edit <code>src/App.tsx</code> and save to reload
12 </>
13 ),
14 fr: (
15 <>
16 Éditez <code>src/App.tsx</code> et enregistrez pour recharger
17 </>
18 ),
19 es: (
20 <>
21 Edita <code>src/App.tsx</code> y guarda para recargar
22 </>
23 ),
24 }),
25 reactLink: {
26 href: "https://reactjs.org",
27 content: t({
28 en: "Learn React",
29 fr: "Apprendre React",
30 es: "Aprender React",
31 }),
32 },
33 },
34} satisfies DeclarationContent;
35
36export default appContent;انظر كيفية إعلان ملفات إعلان Intlayer الخاصة بك.
الخطوة 5: استخدام Intlayer في الكود الخاص بك
قم بالوصول إلى قواميس المحتوى الخاصة بك في جميع أنحاء تطبيقك:
1import logo from "./logo.svg";
2import "./App.css";
3import { IntlayerProvider, useIntlayer } from "react-intlayer";
4import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
5
6function AppContent() {
7 const content = useIntlayer("app");
8
9 return (
10 <header className="App-header">
11 <img src={logo} className="App-logo" alt="logo" />
12
13 {content.getStarted}
14 <a
15 className="App-link"
16 href={content.reactLink.href.value}
17 target="_blank"
18 rel="noopener noreferrer"
19 >
20 {content.reactLink.content}
21 </a>
22 </header>
23 );
24}
25
26function App() {
27 return (
28 <IntlayerProvider>
29 <div className="App">
30 {/* لاستخدام hook useIntlayer بشكل صحيح، يجب عليك الوصول إلى بياناتك في مكون فرعي */}
31 <AppContent />
32 </div>
33 <div className="absolute bottom-5 right-5 z-50">
34 <LocaleSwitcher />
35 </div>
36 </IntlayerProvider>
37 );
38}
39
40export default App;ملاحظة: إذا كنت ترغب في استخدام المحتوى الخاص بك في سمة string، مثل alt، title، href، aria-label، إلخ، يجب عليك استدعاء قيمة الدالة، مثل:
tsx1<img src={content.image.src.value} alt={content.image.value} />
(اختياري) الخطوة 6: تغيير لغة المحتوى الخاص بك
لتغيير لغة المحتوى الخاص بك، يمكنك استخدام الدالة setLocale المقدمة بواسطة hook useLocale. تتيح لك هذه الدالة تعيين لغة التطبيق وتحديث المحتوى وفقًا لذلك.
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};(اختياري) الخطوة 7: إضافة توجيه محلي إلى تطبيقك
الغرض من هذه الخطوة هو إنشاء مسارات فريدة لكل لغة. هذا مفيد من الناحية SEO وURLs الصديقة لـSEO. مثال:
1// /dashboard
2// /es/dashboard
3// /fr/dashboardبشكل افتراضي، لا يتم إضافة بادئة إلى المسارات للغة الافتراضية. إذا كنت ترغب في إضافة بادئة للغة الافتراضية، يمكنك تعيين خيار middleware.prefixDefault إلى true في تكوينك. انظر وثائق التكوين لمزيد من المعلومات.
لإضافة توجيه محلي إلى تطبيقك، يمكنك إنشاء مكون LocaleRouter يلتف حول مسارات تطبيقك ويتعامل مع التوجيه القائم على اللغة. إليك مثال باستخدام React Router:
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 = removeLocaleFromUrl(
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);(اختياري) الخطوة 8: تغيير URL عند تغيير اللغة
لتغيير URL عند تغيير اللغة، يمكنك استخدام خاصية onLocaleChange المقدمة من hook useLocale. بالتوازي، يمكنك استخدام useLocation و useNavigate hooks من react-router-dom لتحديث مسار URL.
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};تكوين TypeScript
تستخدم Intlayer تحسين وحدات لتوفير مزايا TypeScript وجعل قاعدة التعليمات البرمجية الخاصة بك أقوى.
تأكد من أن تكوين TypeScript الخاص بك يتضمن الأنواع المولدة تلقائيًا.
1// tsconfig.json
2
3{
4 // تكوين مخصص خاص بك
5 include: [
6 "src",
7 "types", // <- تضمين الأنواع المولدة تلقائيًا
8 ],
9}تكوين Git
يوصى بتجاهل الملفات المولدة بواسطة Intlayer. يتيح لك ذلك تجنب الالتزام بها إلى مستودع Git الخاص بك.
للقيام بذلك، يمكنك إضافة التعليمات التالية إلى ملف .gitignore الخاص بك:
1# تجاهل الملفات المولدة بواسطة Intlayer
2.intlayerإذا كان لديك فكرة لتحسين هذه الوثيقة، فلا تتردد في المساهمة من خلال تقديم طلب سحب على GitHub.
رابط GitHub للتوثيق