ترجم تطبيق Expo و React Native الخاص بك | التدويل (i18n)

جدول المحتويات

لماذا Intlayer على البدائل؟

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

1. 1

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

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8

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

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

   bash

   نسخ المحتوى

   نسخ الكود

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

   npm install intlayer react-native-intlayer

   الحزم

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

   • react-native-intlayer
     تكامل React Native الذي يوفر موفّري السياق وReact hooks التي ستستخدمها للحصول على اللغات وتبديلها، وpolyfills لـ React Native، وإضافة Metro لدمج Intlayer مع مجمع React Native. يُعيد تصدير كل شيء من react-intlayer، لذلك تحتاج فقط إلى هذه الحزمة الواحدة في تطبيق React Native.

   ---

2. 2

   إنشاء تكوين Intlayer

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

   intlayer.config.ts

   نسخ المحتوى

   نسخ الكود

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

   /**
    * إذا لم تكن أنواع Locales متوفرة، حاول تعيين moduleResolution إلى "bundler" في ملف tsconfig.json الخاص بك
    */
   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

   إضافة ملحق Metro

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

   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);})();

   ملاحظة: configMetroIntlayer هي دالة غير متزامنة (promise). استخدم configMetroIntlayerSync بدلاً من ذلك إذا كنت تريد استخدامها بشكل متزامن، أو تجنب IFFE (التعبير الدالي المستدعى فورًا). ملاحظة: configMetroIntlayerSync لا تسمح ببناء قواميس Intlayer عند بدء تشغيل الخادم

4. 4

   إضافة موفّر Intlayer

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

   قم دائمًا بالاستيراد من react-native-intlayer. يتضمن IntlayerProvider الخاص به polyfills لواجهة برمجة تطبيقات الويب المستخدمة بواسطة Intlayer، والحزمة تُعيد تصدير جميع الخطافات والأدوات من react-intlayer.

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

   app/_layout.tsx

   نسخ المحتوى

   نسخ الكود

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

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

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
   • إلخ.

   Expo Router (الويب): احتفظ بملفات .content.* خارج مجلد app/. يعامل Expo Router كل ملف JavaScript/TypeScript داخل app/ كمسار. على الويب، يقوم اكتشاف المسار بمسح نظام الملفات مباشرة ولا يحترم resolver.blockList الخاص بـ Metro، لذلك يتم تسجيل *.content.ts الموجود في نفس المكان كمسار. حتى أن ملفًا مثل app/(tabs)/_layout.content.ts يتم تحليله كتخطيط (تُقرأ اللاحقة .content كلاحقة للمنصة)، مما يتعارض مع _layout.tsx الحقيقي ويطرح الخطأ:

   plaintext

   نسخ المحتوى

   نسخ الكود

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

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.

   ضع تصريحاتك في مجلد خارج app/ (على سبيل المثال content/ أو src/content/). يكتشف Intlayer ملفات .content.* في أي مكان في المشروع ويتم الإشارة إلى القواميس من خلال key الخاص بها، لذلك لا توجد حاجة لتغيير الاستيرادات. على التطبيقات الأصلية (native)، هذا غير مطلوب (يخفيها blockList الخاص بـ Metro بالفعل)، ولكن استخدام مجلد غير app/ يحافظ على عمل كلتا المنصتين.

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

   src/app.content.tsx

   نسخ المحتوى

   نسخ الكود

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

   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({
         en: "Welcome!",
         fr: "Bienvenue!",
         es: "¡Bienvenido!",
       }),
     },
   } satisfies Dictionary;
   
   export default homeScreenContent;

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

   ---

6. 6

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

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

   مثال

   app/(tabs)/index.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-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 للحصول على النص الفعلي.

   إذا كان تطبيقك موجودًا بالفعل، يمكنك استخدام مترجم Intlayer، بالإضافة إلى أمر الاستخراج، لتحويل آلاف المكونات في ثانية واحدة.

   ---

7. 7

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

   اختياري

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

   src/components/LocaleSwitcher.tsx

   نسخ المحتوى

   نسخ الكود

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

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { setLocale, availableLocales } = useLocale();
   
     return (
       <View style={styles.container}>
         {availableLocales.map((locale) => (
           <TouchableOpacity
             key={locale}
             style={styles.button}
             onPress={() => setLocale(locale)}
           >
             <Text style={styles.text}>{getLocaleName(locale)}</Text>
           </TouchableOpacity>
         ))}
       </View>
     );
   };
   
   const styles = StyleSheet.create({
     container: {
       flexDirection: "row",
       justifyContent: "center",
       alignItems: "center",
       gap: 8,
     },
     button: {
       paddingVertical: 6,
       paddingHorizontal: 12,
       borderRadius: 6,
       backgroundColor: "#ddd",
     },
     text: {
       fontSize: 14,
       fontWeight: "500",
       color: "#333",
     },
   });

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

   راجع useLocale docs لمزيد من التفاصيل.

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

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

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

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

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

تكوين Git

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

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

إضافة VS Code

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

التثبيت من سوق VS Code

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

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

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

التعمق أكثر

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

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

التصحيح

React Native قد يكون أقل استقراراً من React Web، لذلك انتبه جيداً لمحاذاة الإصدارات.

يستهدف Intlayer بشكل أساسي Web Intl API؛ على React Native يجب عليك تضمين polyfills المناسبة.

قائمة التحقق:

• استخدم أحدث إصدارات intlayer و react-native-intlayer.
• قم بتفعيل polyfill الخاص بـ Intlayer.
• إذا كنت تستخدم getLocaleName أو أدوات أخرى قائمة على Intl-API، قم باستيراد هذه polyfills مبكراً (على سبيل المثال في index.js أو App.tsx):

import "intl";import "@formatjs/intl-getcanonicallocales/polyfill";import "@formatjs/intl-locale/polyfill";import "@formatjs/intl-pluralrules/polyfill";import "@formatjs/intl-displaynames/polyfill";import "@formatjs/intl-listformat/polyfill";import "@formatjs/intl-numberformat/polyfill";import "@formatjs/intl-relativetimeformat/polyfill";import "@formatjs/intl-datetimeformat/polyfill";

• تحقق من إعدادات Metro الخاصة بك (resolver aliases و asset plugins و مسارات tsconfig) إذا فشل استيراد الوحدات.