# General Translation React SDKs (gt-react, gt-next): Быстрый старт React
URL: https://generaltranslation.com/ru/docs/react/react-quickstart.mdx
---
title: Быстрый старт React
description: Добавьте поддержку нескольких языков в React-приложение с серверным рендерингом с помощью General Translation менее чем за 10 минут.
related:
links:
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
---
# Быстрый старт React
К концу этого руководства ваше React-приложение с серверным рендерингом будет отображать контент на нескольких языках, а пользователи смогут переключать язык через соответствующий переключатель.
**Предварительные требования:**
* React-приложение с серверным рендерингом (React Router или собственная SSR-настройка)
* Node.js 18+
**Примечание:** Если ваше приложение полностью рендерится в браузере с Vite, вместо этого используйте руководство [Быстрый старт SPA](/docs/react/react-spa-quickstart). В нём компонент provider вообще не используется.
## Быстрый старт [#quickstart]
### 1. Установите пакеты
`gt-react` — библиотека, которая обеспечивает переводы в вашем приложении. `gt` — это CLI, который подготавливает переводы для Production.
```bash
npm i gt-react
npm i -D gt
```
```bash
yarn add gt-react
yarn add --dev gt
```
```bash
bun add gt-react
bun add --dev gt
```
```bash
pnpm add gt-react
pnpm add --save-dev gt
```
### 2. Создайте конфигурационный файл перевода
Создайте файл **`gt.config.json`** в корне проекта. В нём библиотеке указывается, какие языки вы поддерживаете:
```json title="gt.config.json"
{
"defaultLocale": "en",
"locales": ["es", "fr", "ja"],
"files": {
"gt": {
"output": "src/_gt/[locale].json"
}
}
}
```
* **`defaultLocale`** — язык, на котором написано ваше приложение (исходный язык).
* **`locales`** — языки, на которые вы хотите перевести приложение. Выберите любые из [списка поддерживаемых локалей](/docs/platform/dashboard/reference/supported-locales).
* **`files`** — указывает CLI, где сохранять файлы перевода. Путь `output` должен совпадать с путём импорта в функции `loadTranslations` (шаг 3).
### 3. Создайте загрузчик переводов
Создайте функцию `loadTranslations`, которая загружает файл перевода для локали. На сервере она выполняется при рендеринге; CLI генерирует файлы, когда вы запускаете `npx gt translate`:
```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
try {
const translations = await import(`./_gt/${locale}.json`);
return translations.default;
} catch (error) {
return {};
}
}
```
### 4. Инициализируйте библиотеку
Вызовите **`initializeGT`** на уровне модуля в файле, который загружается и на сервере, и на клиенте — естественнее всего сделать это в корневом маршруте или layout. Это однократно регистрирует вашу конфигурацию и загрузчик переводов; конфигурация остаётся неизменной на протяжении всего времени работы приложения:
```tsx title="src/routes/root.tsx"
import { initializeGT } from 'gt-react';
import gtConfig from '../../gt.config.json';
import loadTranslations from '../loadTranslations';
initializeGT({
defaultLocale: gtConfig.defaultLocale,
locales: gtConfig.locales,
loadTranslations,
});
```
### 5. Загружайте переводы на сервере
В loader корневого маршрута (или аналогичном серверном обработчике) определите локаль запроса и получите снимок переводов с помощью **`getTranslationsSnapshot`**, затем передайте их в **``**:
```tsx title="src/routes/root.tsx"
import {
GTProvider,
getTranslationsSnapshot,
parseLocale,
} from 'gt-react';
// В загрузчике маршрута (конкретный API зависит от вашего фреймворка)
export async function loader({ request }) {
const locale = parseLocale(request); // [!code highlight]
return {
locale,
translations: await getTranslationsSnapshot(locale), // [!code highlight]
};
}
export default function Root({ children }) {
const { locale, translations } = useLoaderData();
return (
{children}
);
}
```
### 6. Отметьте текст для перевода
Оберните любой текст, который нужно перевести, в компонент **``**. `` означает "translate":
```tsx title="src/components/Welcome.tsx"
import { T } from 'gt-react';
export default function Welcome() {
return (
Welcome to my app
This content will be translated automatically.
);
}
```
Для обычных строк — например, атрибутов `placeholder` или значений `aria-label` — используйте хук **`useGT`**:
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Добавьте переключатель языка
Добавьте **``**, чтобы пользователи могли переключать язык:
```tsx title="src/components/Header.tsx"
import { LocaleSelector } from 'gt-react';
export default function Header() {
return ;
}
```
Когда пользователь выбирает язык, `gt-react` сохраняет этот выбор в cookie-файле `generaltranslation.locale` и перезагружает страницу, чтобы сервер заново отрисовал всё в новой локали.
### 8. Настройте переменные окружения (необязательно)
Переводы для разработки по запросу выполняются в браузере. Передайте Project ID и API-ключ для разработки в клиентский код через публичные переменные окружения вашего фреймворка. Никогда не раскрывайте production API-ключ.
В Vite `gt-react` автоматически считывает эти переменные:
```bash title=".env.local"
VITE_GT_PROJECT_ID="your-project-id"
VITE_GT_DEV_API_KEY="your-dev-api-key"
```
Для других фреймворков используйте принятое в них соглашение для клиентских переменных окружения и передавайте публичные значения в `initializeGT`.
Получите бесплатные ключи на [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) или выполнив:
```bash
npx gt auth
```
**Предупреждение:** Для разработки используйте ключ с префиксом `gtx-dev-`. Рабочие ключи (`gtx-api-`) предназначены только для CI/CD.
### 9. Разверните в production
В production переводы генерируются заранее во время сборки (без API-вызовов в реальном времени). Добавьте команду translate в скрипт сборки:
```json title="package.json"
{
"scripts": {
"build": "npx gt translate && "
}
}
```
Задайте переменные окружения для **production** у вашего хостинг-провайдера:
```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
**Предупреждение:** Рабочие ключи начинаются с `gtx-api-` (не `gtx-dev-`). Получить ключ можно на [dash.generaltranslation.com](https://dash.generaltranslation.com). Никогда не публикуйте свой `GT_API_KEY` в открытом доступе.
Вот и всё — теперь ваше приложение поддерживает несколько языков. 🎉
## Устранение неполадок [#troubleshooting]
`gt-react` сохраняет языковые предпочтения пользователя в cookie-файле `generaltranslation.locale`. Если вы раньше тестировали другой язык, этот cookie-файл может переопределять ваш выбор. Очистите cookie-файлы и попробуйте снова.
* [Chrome](https://support.google.com/chrome/answer/95647)
* [Firefox](https://support.mozilla.org/en-US/kb/delete-cookies-remove-info-websites-stored)
* [Safari](https://support.apple.com/en-mn/guide/safari/sfri11471/16.0/mac/11.0)
Это нормально. В development переводы выполняются по запросу (ваш контент переводится в реальном времени через API). В **production этой задержки нет** — все переводы заранее генерируются с помощью `npx gt translate`.
Неоднозначный текст может приводить к неточным переводам. Например, "apple" может означать и фрукт, и компанию. Чтобы помочь системе, добавьте prop `$context`:
```jsx
Apple
```
И ``, и `useGT()` поддерживают параметр `$context`.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables