# General Translation React SDKs (gt-react, gt-next, gt-react-native): Быстрый старт React
URL: https://generaltranslation.com/ru/docs/react/react-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Добавьте несколько языков в React-приложение с серверным рендерингом с помощью General Translation менее чем за 10 минут.
К концу этого руководства ваше 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`](/docs/react/reference/functions/load-translations) (шаг 3).
### 3. Создайте загрузчик переводов
Создайте функцию [`loadTranslations`](/docs/react/reference/functions/load-translations), которая загружает файл перевода для локали. На сервере она выполняется при рендеринге; CLI генерирует файлы, когда вы запускаете [`npx gt translate`](/docs/cli/reference/commands/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`](/docs/react/reference/config#initialize)** на уровне модуля в файле, который загружается и на сервере, и на клиенте — естественнее всего сделать это в корневом маршруте или 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`](/docs/react/reference/functions/get-translations-snapshot)**, затем передайте их в **[``](/docs/react/reference/components/gt-provider)**:
```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. Отметьте текст для перевода
Оберните любой текст, который нужно перевести, в компонент **[``](/docs/react/reference/components/t)**. [``](/docs/react/reference/components/t) означает "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`](/docs/react/reference/hooks/use-gt)**:
```tsx title="src/components/ContactForm.tsx"
import { useGT } from 'gt-react';
export default function ContactForm() {
const gt = useGT();
return ;
}
```
### 7. Добавьте переключатель языка
Добавьте **[``](/docs/react/reference/components/locale-selector)**, чтобы пользователи могли переключать язык:
```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`](/docs/react/reference/config#initialize).
Получите бесплатные ключи на [dash.generaltranslation.com](https://dash.generaltranslation.com/en-US/signin) или выполнив:
```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]
Убедитесь, что в браузере включены cookie-файлы, выбранная локаль указана в `gt.config.json`, а селектор отображается внутри [``](/docs/react/reference/components/gt-provider). Если вы передаёте пользовательский callback [`_reload`](/docs/react/reference/components/gt-provider#reload), убедитесь, что после выбора он выполняет перезагрузку или навигацию.
Это нормально. В development переводы выполняются по запросу (ваш контент переводится в реальном времени через API). В **production этой задержки нет** — все переводы заранее генерируются с помощью [`npx gt translate`](/docs/cli/reference/commands/translate).
Неоднозначный текст может приводить к неточным переводам. Например, "apple" может означать и фрукт, и компанию. Чтобы помочь системе, добавьте prop `$context`:
```jsx
Apple
```
И [``](/docs/react/reference/components/t), и [`useGT()`](/docs/react/reference/hooks/use-gt) поддерживают параметр `$context`.
## Next steps
- /docs/react/guides/translating-jsx
- /docs/react/guides/translating-strings
- /docs/react/guides/managing-locales
- /docs/react/guides/formatting-variables
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.