Начало работы с интернационализацией (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({      ru: "Добро пожаловать!",      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-команды: Изучите Intlayer CLI для выполнения задач, таких как извлечение переводов или проверка отсутствующих ключей.

Наслаждайтесь созданием ваших приложений на React Native с полной поддержкой i18n через Intlayer!