Переведите ваше приложение Expo и React Native | Интернационализация (i18n)

Содержание

Почему Intlayer, а не альтернативы?

По сравнению с основными решениями, такими как react-native-localize или i18next, Intlayer — это решение, включающее такие интегрированные оптимизации, как:

1. 1

   Установите зависимости

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

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer init --interactive
   

   Флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer react-native-intlayer
   

   Пакеты

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

   • react-native-intlayer
     Интеграция с React Native, предоставляющая провайдеры контекста и React-хуки, которые вы будете использовать для получения и переключения локалей, полифилы 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 — это сборщик для 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 включает полифилы для веб-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({
         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",
     },
   });
   

   Это вызывает повторный рендер всех компонентов, использующих контент 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.

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

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

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

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

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

• Визуальный редактор: Используйте Визуальный редактор Intlayer для визуального управления переводами.
• Интеграция с 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), если модули не разрешаются.

Часто задаваемые вопросы