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

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

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

* Приложение React Native CLI (не Expo — для проектов Expo см. [краткое руководство по Expo](/docs/react-native/tutorials/quickstart-expo))
* 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>

***

## Шаг 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
    cd ios && pod install
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-react-native
    yarn add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-react-native
    bun add --dev gt
    cd ios && pod install
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-react-native
    pnpm add --save-dev gt
    cd ios && pod install
    ```
  </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, указав `entryPointFilePath` для входного файла вашего приложения (проверьте поле `"main"` в вашем `package.json`):

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

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    [
      gtPlugin,
      {
        locales: [gtConfig.defaultLocale, ...gtConfig.locales],
        entryPointFilePath: path.resolve(__dirname, 'App.tsx'),
      },
    ],
  ],
};
```

<Accordions>
  <Accordion title="Плагин не работает? Тогда подключите полифилы вручную">
    Установите полифилы 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 (сборщик React Native) не поддерживает динамические импорты, поэтому нужно явно сопоставить каждой локали её файл перевода:

```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 в приложение

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

```tsx title="App.tsx"
import { GTProvider } from 'gt-react-native';
import gtConfig from './gt.config.json';
import { loadTranslations } from './loadTranslations';

export default function App() {
  return (
    <GTProvider
      config={gtConfig}
      loadTranslations={loadTranslations}
      projectId={process.env.GT_PROJECT_ID}
      devApiKey={process.env.GT_API_KEY}
    >
      {/* Содержимое вашего приложения */}
    </GTProvider>
  );
}
```

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

***


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

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

```tsx title="screens/Home.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="screens/Home.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. Они позволяют использовать **on-demand перевод** — приложение будет переводить контент в реальном времени по мере разработки.

Создайте файл **`.env`**:

```bash title=".env"
GT_API_KEY="your-api-key"
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. on-demand перевода в режиме разработки не будет, но вы всё равно можете:

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

***


## Шаг 9: Проверка в работе

Соберите и запустите приложение:

```bash
npx react-native run-ios
# или
npx react-native run-android
```

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

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

***


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

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

```tsx title="screens/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:

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

    Это означает, что нативный модуль не был подключён. Выполните `cd ios && pod install`, затем пересоберите приложение.
  </Accordion>

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

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

    ```bash
    npx react-native start --reset-cache
    ```
  </Accordion>

  <Accordion title="В среде разработки переводы работают медленно">
    Это ожидаемо. В среде разработки переводы выполняются on-demand (контент переводится в реальном времени через API). В **продакшене этой задержки нет** — все переводы заранее генерируются командой `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, кэширование и оптимизация производительности