Запустите перевод контента в своем 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('Введите вашу электронную почту')}
      aria-label={t('Поле для ввода электронной почты')}
    />
  );
}

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

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

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

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

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

2. Запустите сервер разработки:

   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 Tool для получения подробной информации.

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

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

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

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