تدويل تطبيق الموبايل باستخدام Lynx و React عبر Intlayer

انظر قالب التطبيق على GitHub.

لماذا تختار Intlayer مقارنة بالبدائل الأخرى؟

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

1. 1

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

   من مشروع Lynx الخاص بك، قم بتثبيت الحزم التالية:

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer init --interactive
   

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer react-intlayer lynx-intlayer
   

   الحزم

   • intlayer
     أداة i18n الأساسية للتكوين، محتوى القاموس، إنشاء الأنواع، وأوامر CLI.

   • react-intlayer
     تكامل React الذي يوفر موفري السياق وخطافات React التي ستستخدمها في Lynx للحصول على اللغات وتبديلها.

   • lynx-intlayer
     تكامل Lynx الذي يوفر المكون الإضافي لدمج Intlayer مع Lynx bundler.

2. 2

   إنشاء تكوين Intlayer

   في جذر مشروعك (أو في أي مكان مناسب)، قم بإنشاء ملف تكوين Intlayer. قد يبدو كالتالي:

   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;
   

   داخل هذا التكوين، يمكنك:

   • تكوين قائمة اللغات المدعومة.
   • تعيين لغة افتراضية.
   • لاحقًا، يمكنك إضافة خيارات أكثر تقدمًا (مثل السجلات، أدلة المحتوى المخصصة، إلخ).
   • راجع وثائق تكوين Intlayer للمزيد.
3. 3

   إضافة المكون الإضافي Intlayer إلى Lynx bundler

   لاستخدام Intlayer مع Lynx، تحتاج إلى إضافة المكون الإضافي إلى ملف lynx.config.ts الخاص بك:

   lynx.config.ts

   نسخ المحتوى

   نسخ الكود

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

   import { defineConfig } from "@lynx-js/rspeedy";
   import { pluginIntlayerLynx } from "lynx-intlayer/plugin";
   
   export default defineConfig({
     plugins: [
       // ... مكونات إضافية أخرى
       pluginIntlayerLynx(),
     ],
   });
   

4. 4

   إضافة موفر Intlayer

   للحفاظ على تزامن لغة المستخدم عبر تطبيقك، تحتاج إلى تغليف المكون الجذري الخاص بك باستخدام المكون IntlayerProvider من react-intlayer.

   أيضًا، تحتاج إلى إضافة ملف وظيفة intlayerPolyfill لضمان عمل Intlayer بشكل صحيح.

   src/index.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { root } from "@lynx-js/react";
   
   import { App } from "./App.js";
   import { IntlayerProvider } from "react-intlayer";
   import { intlayerPolyfill } from "lynx-intlayer";
   
   intlayerPolyfill();
   
   root.render(
     <IntlayerProvider>
       <App />
     </IntlayerProvider>
   );
   
   if (import.meta.webpackHot) {
     import.meta.webpackHot.accept();
   }
   

5. 5

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

   قم بإنشاء ملفات إعلان المحتوى في أي مكان في مشروعك (عادةً داخل src/)، باستخدام أي من تنسيقات الامتداد التي يدعمها Intlayer:

   • .content.json
   • .content.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • إلخ.

   مثال:

   src/app.content.ts

   نسخ المحتوى

   نسخ الكود

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

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "React",
       subtitle: t({
         en: "on Lynx",
         fr: "sur Lynx",
         es: "en Lynx",
       }),
       description: t({
         ar: "اضغط على الشعار واستمتع!",
         en: "Tap the logo and have fun!",
         fr: "Appuyez sur le logo et amusez-vous!",
         es: "¡Toca el logo y diviértete!",
       }),
       hint: [
         t({
           ar: "تعديل",
           en: "Edit",
           fr: "Modifier",
           es: "Editar",
         }),
         " src/App.tsx ",
         t({
           ar: "لرؤية التحديثات!",
           en: "to see updates!",
           fr: "pour voir les mises à jour!",
           es: "para ver actualizaciones!",
         }),
       ],
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

   وثائق محتوى Intlayer
6. 6

   استخدام Intlayer في مكوناتك

   استخدم الخطاف useIntlayer في المكونات الفرعية للحصول على المحتوى المحلي.

   src/App.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { useCallback, useState } from "@lynx-js/react";
   import { useIntlayer } from "react-intlayer";
   
   import "./App.css";
   import arrow from "./assets/arrow.png";
   import lynxLogo from "./assets/lynx-logo.png";
   import reactLynxLogo from "./assets/react-logo.png";
   import { LocaleSwitcher } from "./components/LocaleSwitcher.jsx";
   
   export const App = () => {
     const [alterLogo, setAlterLogo] = useState(false);
     const { title, subtitle, description, hint } = useIntlayer("app");
     const onTap = useCallback(() => {
       // تغيير الخلفية فقط
       setAlterLogo(!alterLogo);
     }, [alterLogo]);
   
     return (
       <view>
         <view className="Background" />
         <view className="App">
           <view className="Banner">
             <view className="Logo" bindtap={onTap}>
               {alterLogo ? (
                 <image src={reactLynxLogo} className="Logo--react" />
               ) : (
                 <image src={lynxLogo} className="Logo--lynx" />
               )}
             </view>
             <text className="Title">{title}</text>
             <text className="Subtitle">{subtitle}</text>
           </view>
           <view className="Content">
             <image src={arrow} className="Arrow" />
             <text className="Description">{description}</text>
             <text className="Hint">
               {hint[0]}
               <text style={{ fontStyle: "italic" }}>{hint[1]}</text>
               {hint[2]}
             </text>
           </view>
           <LocaleSwitcher />
           <view style={{ flex: 1 }}></view>
         </view>
       </view>
     );
   };
   

   عند استخدام content.someKey في الخصائص النصية (مثل خاصية title للزر أو خاصية children لمكون Text)، قم باستدعاء content.someKey.value للحصول على النص الفعلي.

7. 7

   تغيير لغة التطبيق

   لتبديل اللغات من داخل مكوناتك، يمكنك استخدام طريقة setLocale من الخطاف useLocale:

   src/components/LocaleSwitcher.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { type FC } from "react";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { setLocale, availableLocales, locale } = useLocale();
   
     return (
       <view
         style={{
           display: "flex",
           flexDirection: "row",
           justifyContent: "center",
           alignItems: "center",
           gap: 10,
         }}
       >
         {availableLocales.map((localeEl) => (
           <text
             key={localeEl}
             style={{
               color: localeEl === locale ? "#fff" : "#888",
               fontSize: "12px",
             }}
             bindtap={() => setLocale(localeEl)}
           >
             {getLocaleName(localeEl)}
           </text>
         ))}
       </view>
     );
   };
   

   هذا يؤدي إلى إعادة رسم جميع المكونات التي تستخدم محتوى Intlayer، مما يعرض الآن الترجمات للغة الجديدة.

   راجع وثائق useLocale لمزيد من التفاصيل.

   وثائق useLocale

إعداد TypeScript (إذا كنت تستخدم TypeScript)

يقوم Intlayer بإنشاء تعريفات الأنواع في مجلد مخفي (افتراضيًا .intlayer) لتحسين الإكمال التلقائي واكتشاف أخطاء الترجمة:

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

هذا ما يتيح ميزات مثل:

• الإكمال التلقائي لمفاتيح القاموس.
• التحقق من النوع الذي يحذرك إذا قمت بالوصول إلى مفتاح غير موجود أو عدم تطابق النوع.

إعداد Git

لتجنب الالتزام بالملفات التي يتم إنشاؤها تلقائيًا بواسطة Intlayer، أضف التالي إلى ملف .gitignore الخاص بك:

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

إضافة VS Code

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

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

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

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

المزيد من الاستكشاف