Получайте уведомления о предстоящих релизах Intlayer
    Создание:2025-06-18Последнее обновление:2025-06-29

    Начало работы с интернационализацией (i18n) с Intlayer и React Native

    Смотрите Шаблон приложения на GitHub.

    Что такое Intlayer?

    Intlayer — это инновационная, открытая библиотека интернационализации (i18n), которая упрощает поддержку многоязычности в современных приложениях. Она работает во многих средах JavaScript/TypeScript, включая React Native (через пакет react-intlayer).

    С помощью Intlayer вы можете:

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

    Шаг 1: Установка зависимостей

    В вашем проекте React Native установите следующие пакеты:

    bash
    npm install intlayer react-intlayernpm install --save-dev react-native-intlayer

    Пакеты

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

    • react-intlayer
      Интеграция с React, предоставляющая провайдеры контекста и React-хуки, которые вы будете использовать в React Native для получения и переключения локалей.

    • react-native-intlayer
      Интеграция с React Native, предоставляющая плагин Metro для интеграции Intlayer с бандлером React Native.


    Шаг 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: Добавьте плагин 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);})();

    Шаг 4: Добавьте провайдер Intlayer

    Чтобы синхронизировать язык пользователя по всему вашему приложению, необходимо обернуть корневой компонент в компонент IntlayerProvider из react-intlayer.

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

    app/_layout.tsx
    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 defaultLocale={getDeviceLocale()}>      <Stack>        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />      </Stack>    </IntlayerProviderContent>  );};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):

    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 по контенту.


    Шаг 4: Использование Intlayer в ваших компонентах

    Используйте хук useIntlayer в дочерних компонентах для получения локализованного контента.

    Пример

    app/(tabs)/index.tsx
    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:

    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-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.

    Настройка TypeScript (если вы используете TypeScript)

    Intlayer генерирует определения типов в скрытой папке (по умолчанию .intlayer), чтобы улучшить автодополнение и выявлять ошибки перевода:

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

    Это обеспечивает такие возможности, как:

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

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

    Чтобы избежать коммита автоматически сгенерированных файлов Intlayer, добавьте следующее в ваш .gitignore:

    plaintext
    # Игнорировать файлы, сгенерированные Intlayer.intlayer

    Расширение VS Code

    Чтобы улучшить опыт разработки с Intlayer, вы можете установить официальное Расширение Intlayer для VS Code.

    Установить из VS Code Marketplace

    Это расширение предоставляет:

    • Автодополнение для ключей переводов.
    • Обнаружение ошибок в реальном времени для отсутствующих переводов.
    • Встроенный просмотр переведённого контента.
    • Быстрые действия для удобного создания и обновления переводов.

    Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer для VS Code.


    Продвинутые возможности

    • Визуальный редактор: Используйте Визуальный редактор Intlayer для визуального управления переводами.
    • Интеграция с CMS: Вы также можете вынести и получать содержимое вашего словаря из CMS.
    • Команды CLI: Изучите Intlayer CLI для таких задач, как извлечение переводов или проверка отсутствующих ключей.

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


    История документа

    • 5.5.10 - 2025-06-29: Инициализация истории
    Получайте уведомления о предстоящих релизах Intlayer