البدء في التدويل (i18n) باستخدام Intlayer و Lynx و React

    ما هو Intlayer؟

    Intlayer هو مكتبة تدويل (i18n) مبتكرة ومفتوحة المصدر تُبسط دعم اللغات المتعددة في التطبيقات الحديثة. يعمل في العديد من بيئات JavaScript/TypeScript، بما في ذلك Lynx (عبر حزمة react-intlayer).

    مع Intlayer، يمكنك:

    • إدارة الترجمات بسهولة باستخدام القواميس التصريحية على مستوى المكونات.
    • ضمان دعم TypeScript مع الأنواع التي يتم إنشاؤها تلقائيًا.
    • تخصيص المحتوى ديناميكيًا، بما في ذلك سلاسل واجهة المستخدم (وفي React للويب، يمكنه أيضًا تخصيص بيانات HTML الوصفية، إلخ).
    • الاستفادة من الميزات المتقدمة، مثل اكتشاف اللغة الديناميكي والتبديل.

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

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

    bash
    npm install intlayer react-intlayer lynx-intlayer

    الحزم

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

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

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


    الخطوة 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: إضافة المكون الإضافي 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: إضافة موفر 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: إعلان المحتوى الخاص بك

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

    • .content.ts
    • .content.mjs
    • .content.cjs
    • .content.json
    • إلخ.

    مثال (TypeScript مع عقد TSX لـ Lynx):

    src/app.content.tsx
    import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: "React",    subtitle: t({      ar: "على Lynx",      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.


    الخطوة 4: استخدام 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 للحصول على النص الفعلي.


    (اختياري) الخطوة 5: تغيير لغة التطبيق

    لتبديل اللغات من داخل مكوناتك، يمكنك استخدام طريقة 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 لمزيد من التفاصيل.

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

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

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

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

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

    إعداد Git

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

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

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

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

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