Перекладіть ваш додаток 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 для отримання та перемикання локалей, поліфіли React Native, а також плагін Metro для інтеграції Intlayer з бандлером React Native. Він реекспортує все з react-intlayer, тому у застосунку React Native достатньо лише цього одного пакету.

   ---

2. 2

   Створіть конфігурацію Intlayer

   У корені вашого проєкту (або в будь-якому зручному місці) створіть файл Intlayer config. Він може виглядати так:

   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 — це бандлер для 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 — це функція, яка повертає проміс. Використовуйте configMetroIntlayerSync, якщо хочете виконувати це синхронно, або уникайте IIFE (Immediately Invoked Function Expression). Примітка: configMetroIntlayerSync не дозволяє будувати словники intlayer під час запуску сервера

4. 4

   Додайте провайдер Intlayer

   Щоб синхронізувати мову користувача по всьому застосунку, потрібно обгорнути кореневий компонент компонентом IntlayerProvider з react-native-intlayer.

   Завжди імпортуйте з react-native-intlayer. Його IntlayerProvider включає поліфіли для Web API, які використовує 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, тому жодних змін імпорту не потрібно. У нативних програмах це не обов'язково (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({
         uk: "Ласкаво просимо!",
         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 Compiler у поєднанні з командою extract, щоб перетворити тисячі компонентів за одну секунду.

   ---

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",
     },
   });

   Це спричиняє повторний рендер (re-render) усіх компонентів, що використовують контент Intlayer, тепер вони відображають переклади для нової локалі.

   Див. документацію по useLocale для докладніших відомостей.

Налаштування TypeScript (якщо ви використовуєте TypeScript)

Intlayer генерує визначення типів у прихованій теці (за замовчуванням .intlayer), щоб покращити автодоповнення та виявляти помилки перекладів:

// tsconfig.json{  // ... ваша існуюча конфігурація TS  "include": [    "src", // ваш вихідний код    ".intlayer/types/**/*.ts", // <-- переконайтеся, що згенеровані типи включені    // ... все інше, що ви вже включаєте  ],}

Це дозволяє такі можливості, як:

• Автодоповнення для ключів вашого словника.
• Перевірка типів, що попереджає, якщо ви звертаєтеся до неіснуючого ключа або є невідповідність типів.

Конфігурація Git

Щоб уникнути коміту автоматично згенерованих Intlayer файлів, додайте наступне до вашого .gitignore:

# Ігнорувати файли, згенеровані Intlayer.intlayer

Розширення для VS Code

Щоб покращити досвід розробки з Intlayer, ви можете встановити офіційне Intlayer VS Code Extension.

Встановити з VS Code Marketplace

Це розширення надає:

• Автодоповнення для ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудований перегляд перекладеного вмісту.
• Швидкі дії для простого створення та оновлення перекладів.

Для детальнішого опису використання розширення зверніться до документації Intlayer VS Code Extension.

Додаткові ресурси

• Візуальний редактор: Використовуйте Intlayer Visual Editor для візуального керування перекладами.
• Інтеграція з CMS: Ви також можете винести та отримувати вміст вашого словника з CMS.
• Команди CLI: Ознайомтеся з Intlayer CLI для завдань, таких як вилучення перекладів або перевірка відсутніх ключів.

Насолоджуйтесь створенням ваших додатків на React Native з повноцінною i18n за допомогою Intlayer!

Налагодження

React Native може бути менш стабільним, ніж React для Web, тому приділяйте особливу увагу узгодженню версій.

Intlayer в першу чергу орієнтований на Web Intl API; на React Native потрібно підключити відповідні поліфіли.

Контрольний список:

• Використовуйте останні версії intlayer та react-native-intlayer.
• Увімкніть Intlayer поліфіл.
• Якщо ви використовуєте getLocaleName або інші утиліти на базі Intl API, імпортуйте ці поліфіли на ранньому етапі (наприклад, в 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 paths), якщо модулі не вдається розв'язати.