# gt-react: General Translation React SDK: Обзор
URL: https://generaltranslation.com/ru/docs/react/introduction.mdx
---
title: Обзор
description: Обзор React SDK от General Translation
---

{/* АВТОМАТИЧЕСКИ СГЕНЕРИРОВАНО: Не редактируйте напрямую. Редактируйте шаблон в content/docs-templates/. */}


## Введение

General Translation React SDK — это библиотека интернационализации (i18n) с открытым исходным кодом для React-приложений.

Она предоставляет полный набор инструментов для интернационализации React-приложения простым и удобным в сопровождении способом, сохраняя функциональный паритет с другими популярными библиотеками i18n.

SDK можно использовать автономно, без платформы General Translation, и по поведению он похож на другие библиотеки i18n.

Однако он также интегрируется с нашей платформой и предоставляет дополнительные возможности:

* Горячая перезагрузка переводов при разработке
* Автоматический перевод с помощью ИИ
* Синхронизация переводов с платформой General Translation
* Нативная интеграция с нашим CDN для переводов

## Основные понятия

В SDK есть 5 основных понятий, которые нужно понимать.

<Steps>
  <Step>
    Компонент [`<GTProvider>`](/docs/react/api/components/gtprovider)
  </Step>

  <Step>
    Компонент [`<T>`](/docs/react/api/components/t)
  </Step>

  <Step>
    Хук [`useGT`](/docs/react/api/strings/use-gt)
  </Step>

  <Step>
    Функция [`msg`](/docs/react/api/strings/msg) для общих строк
  </Step>

  <Step>
    (Необязательно) Хук [`useTranslations`](/docs/react/api/dictionary/use-translations)
  </Step>
</Steps>

## Компонент `<GTProvider>`

Компонент [`<GTProvider>`](/docs/react/api/components/gtprovider) предоставляет приложению контекст перевода, включая текущий язык и соответствующие переводы.

```tsx
import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* Содержимое вашего приложения */}
      </div>
    </GTProvider>
  );
}
```

**Важно:** Провайдер должен оборачивать всё приложение и располагаться как можно выше в дереве компонентов, например в корневом компоненте App.

Подробнее см. в [справочнике API `GTProvider`](/docs/react/api/components/gtprovider).


## Компонент `<T>`

Компонент [`<T>`](/docs/react/api/components/t) — рекомендуемый способ переводить содержимое вашего приложения.

Это React-компонент, которым можно обернуть любой JSX-элемент; он автоматически отображает содержимое этого элемента на поддерживаемом языке.

<Callout type="info">
  По возможности рекомендуем использовать компонент [`<T>`](/docs/react/api/components/t), поскольку он дает наибольшую гибкость при переводе.

  В отличие от строк, компонент [`<T>`](/docs/react/api/components/t) можно использовать для перевода HTML-содержимого, что делает его значительно мощнее обычного перевода строк.
</Callout>

### Примеры

```tsx
<T>
  <div>Hello, world!</div>
</T>
```

```tsx
<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>
```

```tsx
<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>
```

Компонент [`<T>`](/docs/react/api/components/t) работает с [переменными компонентами](/docs/react/guides/variables), такими как [`<Num>`](/docs/react/api/components/num), [`<DateTime>`](/docs/react/api/components/datetime) и [`<Currency>`](/docs/react/api/components/currency), для форматирования динамического содержимого.

См. [руководство по компоненту `<T>`](/docs/react/guides/t), чтобы узнать о разных способах использования компонента [`<T>`](/docs/react/api/components/t).


## Хук `useGT`

[`useGT`](/docs/react/api/strings/use-gt) — это React-хук, который можно использовать аналогично компоненту [`<T>`](/docs/react/api/components/t), но с некоторыми оговорками.

Хук возвращает функцию, которую можно использовать для перевода строк.

```tsx
const gt = useGT();

gt('Hello, world!');
```

По сравнению с компонентом [`<T>`](/docs/react/api/components/t), хук [`useGT`](/docs/react/api/strings/use-gt) дает больше гибкости при работе с кодовой базой.

Например, если у вас сложная структура данных с вложенными строками, использовать компонент [`<T>`](/docs/react/api/components/t) будет сложнее.

```tsx
const gt = useGT();
const data = {
  title: gt('Hello, world!'),
  description: gt('This is a description'),
};
```

См. руководство [Строки](/docs/react/guides/strings), чтобы подробнее узнать о хуке [`useGT`](/docs/react/api/strings/use-gt).


## Функция `msg`

Функция [`msg`](/docs/react/api/strings/msg) используется, чтобы помечать для перевода строки, которые применяются в нескольких компонентах или хранятся в объектах конфигурации.

Это особенно полезно для общего контента, например меток навигации, сообщений в формах или любого текста, который встречается в нескольких местах приложения.

```tsx
// Пометить строки для перевода
import { msg } from 'gt-react';

const navItems = [
  { label: msg('Home'), href: '/' },
  { label: msg('About'), href: '/about' },
  { label: msg('Contact'), href: '/contact' }
];
```

```tsx
// Декодируем и используем помеченные строки
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}
```

Функция [`msg`](/docs/react/api/strings/msg) кодирует строки метаданными перевода, а [`useMessages`](/docs/react/api/strings/use-messages) их декодирует.

<Callout type="info">
  Используйте [`msg`](/docs/react/api/strings/msg) для общего контента, который должен переводиться единообразно во всём приложении. Для контента, относящегося к конкретным компонентам, лучше использовать [`<T>`](/docs/react/api/components/t) или [`useGT`](/docs/react/api/strings/use-gt).
</Callout>

Подробнее о функции `msg` см. в руководстве [«Общие строки»](/docs/react/guides/shared-strings).


## Хук `useTranslations`

Хук [`useTranslations`](/docs/react/api/dictionary/use-translations) — это React-хук, который возвращает функцию для получения переводов по заданному ключу.

```tsx title="dictionary.ts"
const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};
```

```tsx title="App.tsx"
const translate = useTranslations();
translate('hello.world');
```

Это поведение похоже на поведение других библиотек локализации, таких как [`react-i18next`](https://react.i18next.com/) и [`next-intl`](https://next-intl-docs.vercel.app/).

<Callout type="warn">
  Мы не рекомендуем использовать хук [`useTranslations`](/docs/react/api/dictionary/use-translations) в вашем приложении. Частое использование хука [`useTranslations`](/docs/react/api/dictionary/use-translations) усложняет поддержку кодовой базы
  и приводит к значительному техническому долгу.

  Вместо этого мы рекомендуем использовать компонент [`<T>`](/docs/react/api/components/t) или хук [`useGT`](/docs/react/api/strings/use-gt).

  Если вы переходите с другой библиотеки i18n, хук [`useTranslations`](/docs/react/api/dictionary/use-translations) можно использовать как drop-in replacement; он может быть полезен для поэтапной миграции кодовой базы.
</Callout>

См. руководство [Словари](/docs/react/guides/dictionaries), чтобы узнать больше о хуке [`useTranslations`](/docs/react/api/dictionary/use-translations).

См. [справочник API по useTranslations](/docs/react/api/dictionary/use-translations), чтобы узнать больше.

***


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

* Узнайте, как настроить React-проект с помощью SDK: [Быстрый старт](/docs/react)
* Узнайте, как переводить JSX-контент с помощью компонента [`<T>`](/docs/react/api/components/t): [Руководство по переводу JSX](/docs/react/guides/t)
* Узнайте, как переводить строки с помощью хука [`useGT`](/docs/react/api/strings/use-gt): [Руководство по переводу строк](/docs/react/guides/strings)
* Узнайте, как работать с общими строками с помощью функции [`msg`](/docs/react/api/strings/msg): [Руководство по общим строкам](/docs/react/guides/shared-strings)