Перекладіть ваш додаток Expo та React Native | Інтернаціоналізація (i18n)

Зміст

Що таке Intlayer?

Intlayer, це інноваційна, відкрита бібліотека для інтернаціоналізації (i18n), яка спрощує підтримку кількох мов у сучасних додатках. Вона працює у багатьох JavaScript/TypeScript середовищах, включно з React Native (через пакет react-intlayer).

За допомогою Intlayer ви можете:

• Легко керувати перекладами за допомогою декларативних словників на рівні компонентів.
• Забезпечити підтримку TypeScript з автогенерованими типами.
• Динамічно локалізувати контент, включно з текстами інтерфейсу (а в React для web, також HTML-метадані тощо).
• Отримати переваги розширених можливостей, таких як динамічне визначення локалі та її перемикання.

///

Крок 1: Встановіть залежності

Перегляньте шаблон застосунку на GitHub.

У вашому проекті React Native встановіть такі пакети:

npm install intlayer react-intlayernpm install --save-dev react-native-intlayernpx intlayer init

Пакети

• intlayer
  Основний i18n-набір інструментів для конфігурації, вмісту словників, генерації типів та команд CLI.

• react-intlayer
  Інтеграція для React, яка надає провайдери контексту та React hooks, які ви використовуватимете в React Native для отримання та перемикання локалей.

• react-native-intlayer
  Інтеграція для React Native, яка забезпечує плагін Metro для інтеграції Intlayer з бандлером React Native.

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

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

/**
 * Якщо типи 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: Додайте плагін 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);})();

Примітка: configMetroIntlayer, це функція, яка повертає проміс. Використовуйте configMetroIntlayerSync, якщо хочете виконувати це синхронно, або уникайте IFFE (Immediately Invoked Function Expression). Примітка: configMetroIntlayerSync не дозволяє будувати словники intlayer під час запуску сервера

Крок 4: Додайте провайдер Intlayer

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

Переконайтеся, що використовуєте провайдер з react-native-intlayer, а не з react-intlayer. Експорт з react-native-intlayer включає поліфіли для Web API.

Також потрібно додати функцію intlayerPolyfill у ваш файл index.js, щоб забезпечити правильну роботу Intlayer.

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: Оголосіть свій контент

Створіть файли декларації контенту у будь-якому місці вашого проєкту (зазвичай у src/), використовуючи будь-який з форматів розширень, які підтримує Intlayer:

• .content.json
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• тощо.

Приклад (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({
      uk: "Ласкаво просимо!",
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    }),
  },
} satisfies Dictionary;

export default homeScreenContent;

Для детальної інформації про декларації контенту див. документацію Intlayer щодо контенту.

Крок 4: Використання 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");

> Якщо ваш застосунок уже існує, ви можете скористатися [Intlayer Compiler](/uk/doc/compiler) у поєднанні з [командой extract](/uk/doc/concept/cli/extract), щоб перетворити тисячі компонентів за одну секунду.

  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 { View, Text, TouchableOpacity, StyleSheet } from "react-native";
import { getLocaleName } from "intlayer";
import { useLocale } from "react-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", // <-- переконайтеся, що згенеровані типи включені    // ... все інше, що ви вже включаєте  ],}

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

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

Git Configuration

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

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

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

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

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

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

• Autocompletion для ключів перекладу.
• Real-time error detection для відсутніх перекладів.
• Inline previews перекладеного вмісту.
• Quick actions для простого створення та оновлення перекладів.

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

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

• Visual Editor: Використовуйте Intlayer Visual Editor для візуального керування перекладами.
• CMS Integration: Ви також можете винести та отримувати вміст вашого словника з CMS.
• CLI Commands: Ознайомтеся з Intlayer CLI для завдань, таких як extracting translations або checking missing keys.

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

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

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

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

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

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