Введение

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

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

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

При этом он может интегрироваться с нашей платформой для расширенных возможностей:

• Горячая перезагрузка переводов в режиме разработки
• Автоматические AI‑переводы
• Синхронизация переводов с платформой General Translation
• Нативная интеграция с нашим CDN переводов

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

Есть 5 ключевых понятий, которые нужно знать об SDK.

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

Компонент <GTProvider> предоставляет приложению контекст локализации, включая текущий язык и соответствующие переводы.

import { GTProvider } from 'gt-react';

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

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

См. справочник по API GTProvider для подробностей.

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

Компонент <T> — рекомендуемый способ перевода содержимого в вашем приложении.

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

Примеры

<T>
  <div>Привет, мир!</div>
</T>

<T>
  <div>
    <h1> Вот изображение </h1>
    <img src="https://example.com/image.png" alt="Пример" />
  </div>
</T>

<T>
  Форматирование можно легко выполнять с помощью компонента `<T>`.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

Компонент <T> работает с компонентами для подстановок, такими как <Num>, <DateTime> и <Currency>, для динамического форматирования содержимого.

См. руководство по компоненту <T>, чтобы узнать о различных способах использования компонента <T>.

Хук useGT

Хук useGT — это React‑хук, который можно использовать аналогично компоненту <T>, с некоторыми оговорками.

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

const t = useGT();

t('Привет, мир!');

По сравнению с компонентом <T>, хук useGT дает больше гибкости в вашей кодовой базе.

Например, если у вас сложная структура данных со вложенными строками, использовать компонент <T> будет сложнее.

const t = useGT();
const data = {
  title: t('Привет, мир!'),
  description: t('Это описание'),
};

См. руководство strings, чтобы узнать больше о хуке useGT.

Функция msg

Функция msg используется для пометки строк для перевода, которые используются в нескольких компонентах или хранятся в конфигурационных объектах.

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

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

const navItems = [
  { label: msg('Главная'), href: '/' },
  { label: msg('О нас'), href: '/about' },
  { label: msg('Контакты'), href: '/contact' }
];

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

См. руководство по shared strings, чтобы узнать больше о функции msg.

Хук useTranslations

Хук useTranslations — это React‑хук, который возвращает функцию для получения перевода по указанному ключу.

const dictionary = {
  hello: {
    world: 'Привет, мир!',
  },
};

const translate = useTranslations();
translate('hello.world');

Это поведение похоже на другие библиотеки для локализации, такие как react-i18next и next-intl.

См. руководство dictionaries, чтобы узнать больше о хуке useTranslations.

См. справочник по API useTranslations для получения дополнительной информации.

Дальнейшие шаги

• Узнайте, как настроить React‑проект с помощью SDK: Быстрый старт
• Узнайте, как переводить JSX‑контент с помощью компонента <T>: Руководство по переводу JSX
• Узнайте, как переводить строки с помощью хука useGT: Руководство по переводу строк
• Узнайте об общих строках с функцией msg: Руководство по общим строкам