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

ما هو Intlayer؟

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

مع Intlayer، يمكنك:

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

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

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

npm install intlayer react-intlayer react-native-intlayer

الحزم

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

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

• react-native-intlayer
  تكامل React Native الذي يوفر إضافة Metro لدمج Intlayer مع مجمع React Native.

الخطوة 2: إنشاء تكوين Intlayer

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

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: إضافة إضافة Metro

Metro هو مجمع لـ React Native. وهو المجمع الافتراضي لمشاريع React Native التي تم إنشاؤها باستخدام أمر react-native init. لاستخدام Intlayer مع Metro، تحتاج إلى إضافة الإضافة إلى ملف metro.config.js الخاص بك:

const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

الخطوة 4: إضافة موفر Intlayer

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

قم بتغليف مكون الجذر أو المستوى الأعلى الخاص بك بـ IntlayerProvider من react-intlayer.

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

import { Stack } from "expo-router";import { getLocales } from "expo-localization";import { IntlayerProviderContent } from "react-intlayer";import { intlayerPolyfill } from "react-native-intlayer";import { type FC } from "react";intlayerPolyfill();const getDeviceLocale = () => getLocales()[0]?.languageTag;const RootLayout: FC = () => {  return (    <IntlayerProviderContent locale={getDeviceLocale()}>      <Stack>        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />      </Stack>    </IntlayerProviderContent>  );};export default RootLayout;

الخطوة 5: إعلان المحتوى الخاص بك

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

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

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

import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";/** * قاموس المحتوى لنطاق "app" الخاص بنا */import { t, type Dictionary } from "intlayer";const homeScreenContent = {  key: "home-screen",  content: {    title: t({      ar: "مرحبًا!",      en: "Welcome!",      fr: "Bienvenue!",      es: "¡Bienvenido!",    }),  },} satisfies Dictionary;export default homeScreenContent;

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

الخطوة 4: استخدام Intlayer في مكوناتك

قم بتغليف مكون الجذر أو المستوى الأعلى بـ IntlayerProvider من react-intlayer. ثم استخدم الخطاف useIntlayer في المكونات الفرعية للحصول على المحتوى المحلي.

مثال

import { Image, StyleSheet, Platform } from "react-native";import { useIntlayer } from "react-intlayer";import { HelloWave } from "@/components/HelloWave";import ParallaxScrollView from "@/components/ParallaxScrollView";import { ThemedText } from "@/components/ThemedText";import { ThemedView } from "@/components/ThemedView";import { type FC } from "react";const HomeScreen = (): FC => {  const { title, steps } = useIntlayer("home-screen");  return (    <ParallaxScrollView      headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}      headerImage={        <Image          source={require("@/assets/images/partial-react-logo.png")}          style={styles.reactLogo}        />      }    >      <ThemedView style={styles.titleContainer}>        <ThemedText type="title">{title}</ThemedText>        <HelloWave />      </ThemedView>    </ParallaxScrollView>  );};const styles = StyleSheet.create({  titleContainer: {    flexDirection: "row",    alignItems: "center",    gap: 8,  },});export default HomeScreen;

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

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

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

import { type FC } from "react";import { Button } from "react-native";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <Button      title="التبديل إلى الفرنسية"      onPress={() => {        setLocale(Locales.FRENCH);      }}    />  );};

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

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

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

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

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

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

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

تكوين Git

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

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

الذهاب أبعد

• المحرر المرئي: استخدم المحرر المرئي لـ Intlayer لإدارة الترجمات بشكل مرئي.
• تكامل CMS: يمكنك أيضًا استخراج محتوى القاموس الخاص بك من CMS.
• أوامر CLI: استكشف CLI الخاص بـ Intlayer للمهام مثل استخراج الترجمات أو التحقق من المفاتيح المفقودة.

استمتع ببناء تطبيقات React Native الخاصة بك مع دعم كامل للتدويل من خلال Intlayer!