Начните переводить контент в вашем React‑приложении за считанные минуты.

Необходимые знания: React, базовые знания JavaScript

Установка

Установите пакеты gt-react и gtx-cli:

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

Настройка

GTProvider

Компонент GTProvider предоставляет контекст переводов вашим React‑компонентам. Он управляет состоянием локали, переводами и предоставляет доступ к хукам useGT и useTranslations.

Добавьте GTProvider в корневой компонент приложения:

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <YourAppContent />
    </GTProvider>
  );
}

Создайте файл gt.config.json в корне вашего проекта:

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Настройте локали для своего проекта. Смотрите поддерживаемые локали для доступных вариантов.

Переменные окружения

Добавьте в файл окружения для горячей перезагрузки во время разработки:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

Получите бесплатные ключи API на dash.generaltranslation.com или выполните:

npx gtx-cli auth

Использование

Теперь вы можете начать интернационализировать контент. Есть два основных подхода:

JSX‑контент с <T>

Оборачивайте JSX‑элементы, чтобы переводить их с помощью компонента <T>:

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>Добро пожаловать в наше приложение!</h1>
    </T>
  );
}

Для динамического контента используйте переменные компоненты, например <Var>:

import { T, Var } from 'gt-react';

function Greeting({ user }) {
  return (
    <T>
      <p>Здравствуйте, <Var>{user.name}</Var>!</p>
    </T>
  );
}

См. руководство по использованию компонента <T> для получения дополнительной информации.

Обычные строки с useGT

Для атрибутов, подписей и обычного текста с использованием хука useGT:

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Введите ваш email')}
      aria-label={t('Поле для ввода email')}
    />
  );
}

См. руководство по переводу строк для получения дополнительных сведений.

Тестирование приложения

Проверьте переводы, переключая языки:

1. Добавьте выпадающий список выбора локали с помощью <LocaleSelector>:

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. Запустите dev‑сервер:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Откройте localhost:3000 и переключайте языки через выпадающий список локали.

В режиме разработки переводы загружаются по запросу (возможна небольшая задержка). В продакшене всё уже предпереведено.

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

Развёртывание

Для продакшена необходимо предварительно перевести контент, так как перевод во время выполнения отключён (за исключением <Tx> и tx).

1. Получите продакшн‑API‑ключ на dash.generaltranslation.com.

   Продакшн‑ключи начинаются с gtx-api- (в отличие от dev‑ключей, которые начинаются с gtx-dev-). Подробнее о различиях окружений.

2. Добавьте переменные в CI/CD‑окружение:

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

   Никогда не добавляйте к продакшн‑ключам публичный префикс переменных вашего фреймворка (например, VITE_, REACT_APP_ и т. п.) — они должны оставаться только на стороне сервера.

3. Запустите команду translate, чтобы перевести контент:

   npx gtx-cli translate

   Поведение команды translate настраивается в файле gt.config.json.

   Подробнее см. в справочнике по CLI‑инструменту.

4. Обновите скрипт сборки, чтобы перевод выполнялся до сборки:

   {
     "scripts": {
       "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
     }
   }

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

• Руководство по компоненту <T> — подробный разбор компонента <T> и перевода JSX
• Руководство по переводу строк — использование useGT для перевода строк
• Компоненты для переменных — работа с динамическим контентом с помощью <Var>, <Num> и др.