# react-native: Быстрый старт с React Native и Expo
URL: https://generaltranslation.com/ru/docs/react-native/tutorials/quickstart-expo.mdx
---
title: Быстрый старт с React Native и Expo
description: Добавьте поддержку нескольких языков в приложение Expo менее чем за 10 минут
---

К концу этого руководства ваше приложение Expo сможет отображать контент на нескольких языках, а пользователи — переключать язык через соответствующий переключатель.

**Предварительные требования:**

* Проект Expo (SDK 49+)
* Node.js 18+

<Callout type="warn">
  `gt-react-native` всё ещё находится на экспериментальной стадии и может работать не во всех проектах.
  Если вы столкнётесь с какими-либо проблемами, сообщите нам об этом, [создав issue на GitHub](https://github.com/generaltranslation/gt/issues).
</Callout>

<Callout type="info">
  **Нужна автоматическая настройка?** Выполните `npx gt@latest`, чтобы настроить всё с помощью [мастера настройки](/docs/cli/init). Это руководство описывает ручную настройку.
</Callout>

<Callout type="info">
  Ищете проект на React Native CLI без Expo? См. [быстрый старт для React Native](/docs/react-native/tutorials/quickstart).
</Callout>

***

## Шаг 1: Установите пакеты

`gt-react-native` — библиотека, которая обеспечивает переводы в вашем приложении. `gt` — CLI-инструмент, который подготавливает переводы к продакшену.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-react-native
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react-native
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react-native
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react-native
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## Шаг 2: Создайте файл конфигурации переводов

Создайте файл **`gt.config.json`** в корне проекта. В нём библиотеке указывается, какие языки вы поддерживаете:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "content/[locale].json"
    }
  }
}
```

* **`defaultLocale`** — язык, на котором написано ваше приложение (исходный язык).
* **`locales`** — языки, на которые вы хотите перевести приложение. Выберите любые из [списка поддерживаемых локалей](/docs/platform/supported-locales).
* **`files.gt.output`** — путь, по которому CLI сохраняет файлы перевода. `[locale]` заменяется кодом каждого языка (например, `content/es.json`).

***


## Шаг 3: Настройте полифилы

Среда выполнения JavaScript в React Native не включает API `Intl`, которые нужны `gt-react-native`. Проще всего использовать Babel-плагин, входящий в комплект.

Добавьте его в конфигурацию Babel:

```js title="babel.config.js"
const gtPlugin = require('gt-react-native/plugin');
const gtConfig = require('./gt.config.json');

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      [
        gtPlugin,
        {
          locales: [gtConfig.defaultLocale, ...gtConfig.locales],
          entryPointFilePath: require.resolve('expo-router/entry'),
        },
      ],
    ],
  };
};
```

<Accordions>
  <Accordion title="Плагин Babel не работает? Тогда подключите полифилы вручную">
    Установите полифилы FormatJS и импортируйте их в начале файла точки входа. Вам понадобятся базовые полифилы, а также данные локали для каждого поддерживаемого языка.

    Полный список см. в [документации по полифилам FormatJS](https://formatjs.github.io/docs/polyfills). Как минимум вам понадобятся:

    ```tsx title="index.js"
    import '@formatjs/intl-getcanonicallocales/polyfill';
    import '@formatjs/intl-locale/polyfill';
    import '@formatjs/intl-pluralrules/polyfill-force';
    import '@formatjs/intl-numberformat/polyfill';
    import '@formatjs/intl-datetimeformat/polyfill';
    import '@formatjs/intl-datetimeformat/add-all-tz';

    // Добавьте данные локали для каждого языка:
    import '@formatjs/intl-pluralrules/locale-data/en';
    import '@formatjs/intl-pluralrules/locale-data/es';
    import '@formatjs/intl-numberformat/locale-data/en';
    import '@formatjs/intl-numberformat/locale-data/es';
    // ... повторите для каждой локали и каждого полифила
    ```
  </Accordion>
</Accordions>

***

## Шаг 4: Создайте загрузчик переводов

Metro (сборщик Expo) не поддерживает динамические импорты, поэтому нужно явно сопоставить каждую локаль с соответствующим файлом перевода:

```ts title="loadTranslations.ts"
const translations: Record<string, any> = {
  es: require("@/content/es.json"),
  fr: require("@/content/fr.json"),
  ja: require("@/content/ja.json"),
};

export function loadTranslations(locale: string) {
  return translations[locale] ?? {};
}
```

Эти файлы создаются CLI при запуске `npx gt translate`.

***


## Шаг 5: Добавьте GTProvider в корневой layout

Компонент **`GTProvider`** предоставляет всему приложению доступ к переводам. Добавьте его в корневой layout:

```tsx title="app/_layout.tsx"
import { Slot } from 'expo-router';
import { GTProvider } from 'gt-react-native';
import gtConfig from '../gt.config.json';
import { loadTranslations } from '../loadTranslations';

export default function RootLayout() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
      projectId={process.env.EXPO_PUBLIC_GT_PROJECT_ID}
      devApiKey={process.env.EXPO_PUBLIC_GT_DEV_API_KEY}
    >
      <Slot />
    </GTProvider>
  );
}
```

`GTProvider` управляет состоянием локали и делает переводы доступными для всех дочерних компонентов. Свойство `devApiKey` включает перевод по запросу в процессе разработки.

***


## Шаг 6: Отметьте контент для перевода

Оберните любой текст, который нужно перевести, в компонент **`<T>`**:

```tsx title="app/index.tsx"
import { Text, View } from 'react-native';
import { T } from 'gt-react-native';

export default function Home() {
  return (
    <View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
      <T>
        <Text>This content will be translated automatically.</Text>
      </T>
    </View>
  );
}
```

Всё внутри `<T>` переводится как единое целое.

***


## Шаг 7: Добавьте переключатель языка

Используйте хук **`useLocaleSelector`**, чтобы создать селектор языка. В отличие от `gt-react`, `gt-react-native` не экспортирует готовый компонент `<LocaleSelector>` — интерфейс нужно реализовать самостоятельно с помощью этого хука:

```tsx title="app/index.tsx"
import { Text, View, Pressable } from 'react-native';
import { T, useLocaleSelector } from 'gt-react-native';

export default function Home() {
  const { locales, locale, setLocale } = useLocaleSelector();

  return (
    <View>
      <View style={{ flexDirection: 'row', gap: 8, marginBottom: 16 }}>
        {locales.map((l) => (
          <Pressable key={l} onPress={() => setLocale(l)}>
            <Text style={{ fontWeight: l === locale ? 'bold' : 'normal' }}>{l}</Text>
          </Pressable>
        ))}
      </View>
      <T>
        <Text>Welcome to my app</Text>
      </T>
    </View>
  );
}
```

`useLocaleSelector` возвращает доступные локали, текущую локаль и функцию для её изменения, обеспечивая вам полный контроль над интерфейсом.

***

## Шаг 8: Настройка переменных окружения (необязательно)

Чтобы видеть переводы в режиме разработки, вам понадобятся API-ключи General Translation.

Создайте файл **`.env.local`**. В Expo общедоступные переменные окружения должны иметь префикс `EXPO_PUBLIC_`:

```bash title=".env.local"
EXPO_PUBLIC_GT_DEV_API_KEY="your-dev-api-key"
EXPO_PUBLIC_GT_PROJECT_ID="your-project-id"
```

Получите бесплатные ключи на [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) или выполнив команду:

```bash
npx gt auth
```

<Callout type="warn">
  Для разработки используйте ключ, начинающийся с `gtx-dev-`. Продакшен-ключи (`gtx-api-`) предназначены только для CI/CD.

  Никогда не включайте продакшен-ключи API в бандл приложения и не коммитьте их в систему контроля версий.
</Callout>

<Accordions>
  <Accordion title="Можно ли использовать gt-react-native без ключей API?">
    Да. Без ключей API `gt-react-native` работает как обычная библиотека i18n. Перевод по запросу в процессе разработки будет недоступен, но вы всё равно сможете:

    * Вручную добавлять собственные файлы переводов
    * Использовать все компоненты (`<T>`, `<Var>`, `LocaleSelector` и т. д.)
    * Запустить `npx gt generate`, чтобы создать шаблоны файлов переводов, а затем перевести их самостоятельно
  </Accordion>
</Accordions>

***


## Шаг 9: Посмотрите в работе

Запустите сборку в режиме разработки:

```bash
npx expo start --dev-client
```

<Callout type="warn">
  **Expo Go не работает** с `gt-react-native`, потому что пакет включает нативный модуль. Вам понадобится [сборка для разработки](https://docs.expo.dev/develop/development-builds/introduction/):

  ```bash
  npx expo run:ios
  # или
  npx expo run:android
  ```
</Callout>

Используйте переключатель языка, чтобы сменить язык. Вы должны увидеть переведённый контент.

<Callout type="info">
  Во время разработки переводы подгружаются по запросу — при первом переключении на новый язык вы можете ненадолго увидеть состояние загрузки. В продакшене переводы генерируются заранее и загружаются мгновенно.
</Callout>

***


## Шаг 10: Переводите строки, а не только JSX

Для обычных строк — например, атрибутов `placeholder` или значений `accessibilityLabel` — используйте хук **`useGT`**:

```tsx title="app/contact.tsx"
import { TextInput, View } from 'react-native';
import { useGT } from 'gt-react-native';

export default function Contact() {
  const gt = useGT();

  return (
    <View>
      <TextInput
        placeholder={gt('Enter your email')}
        accessibilityLabel={gt('Email input field')}
      />
    </View>
  );
}
```

***


## Шаг 11: Развертывание в продакшен

В продакшене переводы генерируются заранее на этапе сборки (без API-вызовов в реальном времени). Добавьте команду `translate` в скрипт сборки:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

Задайте переменные окружения **продакшен** в CI/CD (они используются только на сервере, а не `EXPO_PUBLIC_`):

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  Ключи для продакшена начинаются с `gtx-api-` (а не `gtx-dev-`). Получите ключ на [dash.generaltranslation.com](https://dash.generaltranslation.com). Никогда не включайте ключи для продакшена в бандл приложения.
</Callout>

Вот и всё — теперь ваше приложение поддерживает несколько языков. 🎉

***


## Устранение неполадок

<Accordions>
  <Accordion title="'GtReactNative' не найден">
    ```
    ERROR  [Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'GtReactNative' could not be found.]
    ```

    Это означает, что нативный модуль не подключён. Распространённые причины:

    1. **Вы используете Expo Go**, а не сборку для разработки. Переключитесь на сборку для разработки:

    ```bash
    npx expo run:ios
    # или
    npx expo run:android
    ```

    2. **Pods устарели (iOS).** Попробуйте переустановить их:

    ```bash
    cd ios && rm -rf build Pods Podfile.lock && pod install && cd ..
    ```
  </Accordion>

  <Accordion title="Ошибка: недопустимые коды локалей">
    ```
    Error: You are using invalid locale codes in your configuration.
    ```

    Обычно это означает, что полифилы настроены неправильно. Убедитесь, что Babel-плагин настроен (или полифилы импортированы вручную), и очистите кэш:

    ```bash
    npx expo start --clear
    ```
  </Accordion>

  <Accordion title="В режиме разработки переводы работают медленно">
    Это ожидаемо. В режиме разработки переводы выполняются по запросу (контент переводится в реальном времени через API). В production этой задержки **нет** — все переводы заранее генерируются командой `npx gt translate`.
  </Accordion>

  <Accordion title="Некоторые переводы неточны">
    Неоднозначный текст может приводить к неточным переводам. Например, &quot;apple&quot; может означать и фрукт, и компанию. Для уточнения добавьте проп `context`:

    ```jsx
    <T context="the technology company">Apple</T>
    ```

    И `<T>`, и `useGT()` поддерживают опцию `context`.
  </Accordion>
</Accordions>

***

## Следующие шаги

* [**Руководство по компоненту `<T>`**](/docs/react-native/guides/t) — Узнайте о переменных, формах множественного числа и продвинутых шаблонах перевода
* [**Руководство по переводу строк**](/docs/react-native/guides/strings) — Подробный разбор `useGT`
* [**Переменные компоненты**](/docs/react-native/guides/variables) — Работайте с динамическим контентом с помощью `<Var>`, `<Num>`, `<Currency>` и `<DateTime>`
* [**Развертывание в продакшен**](/docs/react-native/tutorials/quickdeploy) — Настройка CI/CD, кэширования и оптимизация производительности