# General Translation Knowledge Base: Как добавить i18n в приложение Next.js на App Router?
URL: https://generaltranslation.com/ru/kb/add-i18n-to-nextjs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Начните с gt init, чтобы настроить General Translation в поддерживаемом проекте на App Router, затем разметьте исходное содержимое, создайте переводы и проверьте переключение языка. gt-next хранит тексты прямо в JSX вместе с контекстом перевода, а CLI, редактор в панели управления и Locadex берут на себя генерацию, проверку и последующие обновления. В этом руководстве также показана явная настройка с локальными файлами.
Category: Интернационализация
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

В этом пошаговом руководстве мы добавим английский, испанский и французский языки на небольшую страницу проекта. Мы рассмотрим серверный компонент, клиентский компонент и переключатель языка. Выбранный язык хранится в cookie-файле; URL-адреса с префиксом локали и многоязычное SEO настраиваются отдельно.

`gt-next` от General Translation создан специально для Next.js App Router. Исходные тексты остаются в JSX, где они обретают смысл, а само содержимое напрямую связано с генерацией переводов. Используйте [проп `context`](/docs/react/reference/components/t#context), чтобы пояснить неоднозначные формулировки, а для управления терминологией и тоном задайте [термины Glossary и пользовательские промпты](/docs/platform/dashboard/guides/defining-context-for-translations). Описанный ниже рабочий процесс сборки будет обновлять переводы при каждом изменении источника.

## Video

The video is narrated in English, with English captions.

[How do I add i18n to a Next.js app?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-add-i18n-to-nextjs.mp4) (51 с)

General Translation lets you add i18n with `gt-next`: wrap text in `T` and generate translations. Wrap your config in `withGTConfig`, list your languages, add a `loadTranslations` file, put the `GTProvider` in your root layout, add a `<LocaleSelector>` for the menu, and run `npx gt translate` before `next build`.

## Перед началом работы

Вам понадобится существующий проект на TypeScript с App Router и каталогом `src/app`. Примеры рассчитаны на Next.js 16 и npm. Для Next.js 16 требуется Node.js 20.9 или новее. Если вы начинаете с нуля, сначала выполните шаги из [руководства по установке Next.js](https://nextjs.org/docs/app/getting-started/installation). Для приложений на Pages Router предназначен отдельный [быстрый старт для Pages Router](/docs/react/nextjs-pages-router-quickstart).

В примере явно указаны версии `gt-next@11.4.12` и `gt@2.26.5`. Библиотека распространяется по лицензии MIT и может выполнять рендеринг ваших собственных переводов без учётной записи. Чтобы получать переводы, сгенерированные сервисом, понадобится проект GT и [вход через CLI или ключ для инструментов с ограниченной областью действия](/docs/cli/guides/configuring#credentials). Для автоматических сборок используйте ключ из хранилища секретов вашей CI-системы.

## Начните с команды настройки

Запустите мастер настройки в каталоге приложения:

```bash
npx gt@2.26.5 init
```

Выберите настройку фреймворка React для приложения на App Router, исходный и целевые языки, а также локальную доставку или доставку через CDN. Мастер установит `gt-next`, добавит [`GTProvider`](/docs/react/reference/components/gt-provider) и [`withGTConfig`](/docs/react/nextjs/config), а также создаст `gt.config.json`. При локальной доставке он также создаст загрузчик переводов. Автоматическое изменение кода фреймворка пока экспериментальное: проверьте сгенерированный diff, особенно в местах с уже существующими провайдерами и обёртками конфигурации. [Справочник по настройке](/docs/cli/reference/commands/init).

Разметку контента приложения и генерацию переводов вам по-прежнему нужно выполнить самостоятельно. Если вы хотите, чтобы агент для написания кода довёл задачу до конца, включая проверку, воспользуйтесь [Setup for Agents](https://generaltranslation.com/agent-prompt.md).

В приведённой ниже ручной настройке используется `src/_gt/[locale].json`. По умолчанию мастер сохраняет локальные файлы в `public/_gt/[locale].json`. Либо оставьте сгенерированный им загрузчик вместе с этим путём вывода, либо выполните ручную настройку целиком как альтернативный вариант.

## Явно настройте библиотеку и создайте страницу

### 1. Установите SDK и CLI

Выполните следующие команды в каталоге приложения:

```bash
npm install gt-next@11.4.12
npm install --save-dev gt@2.26.5
```

`gt-next` выполняет рендеринг переводов в приложении. `gt` — инструмент командной строки для сбора и перевода исходного содержимого. [Официальное руководство «Быстрый старт» для Next.js](/docs/react/nextjs-quickstart).

### 2. Настройте Next.js и языки

Оберните существующую конфигурацию Next.js в [`withGTConfig`](/docs/react/nextjs/config). Сохраните все текущие настройки и объедините этот вызов с другими обёртками конфигурации, которые уже используются в проекте.

```ts title="next.config.ts"
import { withGTConfig } from 'gt-next/config';

export default withGTConfig({});
```

Создайте этот файл в корневом каталоге проекта:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

Английский — язык-источник. Испанский и французский — целевые языки. Выходной путь указывает CLI, куда сохранять сгенерированные переводы.

### 3. Добавьте загрузчик локальных переводов

Создайте файл `src/loadTranslations.ts`. Плагин конфигурации обнаружит этот файл и будет использовать его для загрузки сгенерированных файлов локалей:

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

При такой настройке переводы входят в бандл приложения, поэтому в рабочей среде для этого контента не нужно обращаться к General Translation во время выполнения. Обновлённые переводы поставляются вместе со сборкой. [Локальное хранение переводов](/docs/react/guides/storing-translations).

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

### 4. Добавьте провайдер в корневой макет

Измените `src/app/layout.tsx`, как показано ниже. Существующие стили, шрифты, метаданные и другие провайдеры оставьте без изменений.

```tsx title="src/app/layout.tsx"
import type { PropsWithChildren } from 'react';
import { GTProvider } from 'gt-next';
import { getLocale } from 'gt-next/server';

export default async function RootLayout({ children }: PropsWithChildren) {
  const locale = await getLocale();

  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider>
      </body>
    </html>
  );
}
```

[`getLocale`](/docs/react/nextjs/reference/functions/get-locale) определяет текущий язык на сервере. [`GTProvider`](/docs/react/reference/components/gt-provider) предоставляет контекст перевода всему приложению, включая его интерактивные компоненты.

### 5. Перевод JSX и атрибутов полей ввода

Добавьте приведённую ниже страницу. Она по-прежнему остаётся серверным компонентом. [`T`](/docs/react/reference/components/t) помечает статический заголовок и абзац для перевода, а [`LocaleSelector`](/docs/react/reference/components/locale-selector) добавляет раскрывающийся список для выбора языка.

```tsx title="src/app/page.tsx"
import { LocaleSelector, T } from 'gt-next';
import SearchBox from './SearchBox';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Find your next project</h1>
        <p>Explore projects from teams around the world.</p>
      </T>
      <SearchBox />
    </main>
  );
}
```

Создайте поле поиска как клиентский компонент (Client Component). Используйте [`useGT`](/docs/react/reference/hooks/use-gt) для атрибутов со строковыми значениями — например, плейсхолдеров и меток для специальных возможностей:

```tsx title="src/app/SearchBox.tsx"
'use client';

import { useGT } from 'gt-next';

export default function SearchBox() {
  const gt = useGT();

  return (
    <input
      type='search'
      placeholder={gt('Search projects')}
      aria-label={gt('Search projects')}
    />
  );
}
```

[`useGT()`](/docs/react/reference/hooks/use-gt) возвращает функцию перевода напрямую. В асинхронном серверном компоненте вместо него используйте [`getGT`](/docs/react/nextjs/reference/functions/get-gt) из `gt-next/server`.

Не вставляйте динамические значения в виде обычных выражений внутри [`T`](/docs/react/reference/components/t). Чтобы добавить имена, количества или ветви, используйте соответствующие [компоненты переменных и форматирования](/docs/react/guides/formatting-variables).

## Создайте переводы и проверьте результат

### 6. Сгенерируйте переводы

Для автоматического перевода войдите в систему с помощью [`gt login`](/docs/cli/reference/commands/login) и укажите идентификатор проекта либо добавьте ключ API проекта и идентификатор проекта в `.env.local`:

```bash title=".env.local"
GT_PROJECT_ID="your-project-id"
GT_API_KEY="your-project-api-key"
```

Храните ключ в секрете и не добавляйте файл в систему контроля версий. Не раскрывайте `GT_API_KEY` через переменную с префиксом `NEXT_PUBLIC_`. Ключу для инструментов нужны разрешения на чтение и запись файлов и на работу с очередью переводов, а также доступ к контексту, если он используется. Подробнее см. в [документации по ключам API](/docs/platform/dashboard/reference/api-keys).

Создайте переводы:

```bash
npx gt translate
```

Команда отправляет задачи на перевод в General Translation и записывает файлы локалей по пути вывода, указанному в конфигурации. Проверить сгенерированный текст можно в [Редакторе переводов на панели управления](/docs/platform/dashboard/guides/reviewing-translations). Если вы правите скачанные переводы локально, команда [`gt save-local`](/docs/cli/reference/commands/save-local) синхронизирует эти исправления с платформой. Генерация через сервис оплачивается [по факту использования](https://generaltranslation.com/pricing).

Если вы хотите попробовать библиотеку, не обращаясь к сервису перевода, выполните вместо этого:

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) создаёт шаблоны с исходным текстом; **сам текст эта команда не переводит**. Отредактируйте текстовые значения в `src/_gt/es.json` и `src/_gt/fr.json`, сохранив сгенерированные ключи и структуру JSX. Например, переведите испанский заголовок как «Encuentra tu próximo proyecto», а метку поиска — как «Buscar proyectos». Прежде чем считать эти файлы готовыми, переведите и весь остальной текст.

После изменения исходного содержимого снова запустите [`gt generate`](/docs/cli/reference/commands/generate) и проверьте целевые файлы. Команда сохраняет уже имеющиеся целевые значения, добавляет новые записи с исходным текстом и удаляет записи, которых больше нет в источнике.

### 7. Запустите приложение и переключите язык

```bash
npm run dev
```

Откройте адрес, который выведет Next.js. Выберите в раскрывающемся списке сначала испанский, а затем французский язык. Убедитесь, что заголовок, абзац, плейсхолдер и доступная метка поля ввода меняются. Перезагрузите страницу и проверьте, что выбранный язык сохранился, а затем переключитесь обратно на английский.

Если язык в селекторе меняется, а текст остаётся на английском, проверьте файлы целевых языков. Исходные шаблоны, созданные командой [`gt generate`](/docs/cli/reference/commands/generate), содержат английский текст, пока вы их не переведёте. Если страница не компилируется из-за отсутствующего файла локали, повторно выполните соответствующую команду генерации и только потом перезапустите сервер разработки.

## Сборка для рабочей среды

Запустите [`gt validate`](/docs/cli/reference/commands/validate), чтобы выявить синтаксические ошибки в переводах до отправки запроса на перевод в облачный сервис. [Правила ESLint](/docs/react/guides/linting-your-code) от GT добавляют дополнительные проверки на этапе разработки. Если [настроен перевод в режиме разработки](/docs/react/guides/configuring#delivery), вы также сможете просматривать переведённый контент прямо во время редактирования.

Для автоматического процесса перевода добавьте эту команду сборки в существующие скрипты `package.json`:

```json
{
  "scripts": {
    "build": "gt validate && gt translate && next build"
  }
}
```

Задайте `GT_PROJECT_ID` и `GT_API_KEY` в среде сборки. Убедитесь, что CLI, установленный как зависимость для разработки, доступен во время сборки. Добавьте `src/_gt/` в `.gitignore`, если сборка каждый раз заново генерирует результаты перевода.

Если вы выбрали ручной перевод, храните переведённые файлы в системе контроля версий или получайте их из собственного конвейера перевода. Запускайте `next build`, когда эти файлы уже доступны. Не добавляйте переводы, которые поддерживаются вручную, в игнорируемые файлы как воспроизводимые результаты — иначе можно потерять их единственную копию.

После сборки запустите приложение в рабочей среде и повторите проверку переключения языка. Так вы протестируете именно те файлы, которые попадут в релиз, а не будете полагаться только на поведение в среде разработки.

[Инкрементальный процесс перевода](/docs/cli/guides/generating-translations#retranslate) переводит изменённое исходное содержимое и повторно использует подходящие переводы из предыдущих версий. Чтобы автоматизировать и изменения в репозитории, настройте [Locadex](/docs/platform/locadex/guides/configuring-automations): он может интернационализировать новый UI, создавать переводы или синхронизировать изменения локалей через пул-реквесты. Выберите настройки триггеров и проверки, которые подходят для вашего процесса релиза.

Чтобы обновлять переводы без пересборки приложения, используйте [доставку через CDN](/docs/react/nextjs/config) вместо локального загрузчика. Тогда опубликованные правки переводов будут попадать в развёрнутое приложение в соответствии с его настройками версий и кеширования.

Если публичным страницам нужны отдельные URL для каждого языка, перейдите к разделу [Маршрутизация по локалям в App Router](/docs/react/nextjs/app-router-middleware). Приведённый здесь пример на основе cookie-файлов не создаёт страницы `/es` и `/fr` и не настраивает канонические URL и метаданные `hreflang`.

## Промпт для вашего агента для написания кода

Начните с регулярно обновляемого [официального промпта для настройки](https://generaltranslation.com/agent-prompt.md), а затем добавьте к нему это описание функциональности:

```text
Используй английский как язык-источник, а испанский и французский — как целевые языки.
Локализуй страницу проекта с помощью переводов, включённых в сборку локально. Сохрани
существующие провайдеры и маршруты. Добавь заголовок, абзац, поле поиска,
доступную метку (accessible label) и переключатель языка. Используй общую терминологию проекта.
Проверь переключение языка, сохранение выбора после перезагрузки, контент, отрисованный на сервере,
клиентские атрибуты и сборку для рабочей среды. Сообщи, что было фактически протестировано
и что ещё требует языковой проверки. Не выполняй развёртывание и слияние.
```

Подробнее о рабочем процессе в целом читайте в статьях [i18n без файлов перевода](/kb/i18n-without-translation-files) и [Использование агента для написания кода](/kb/ai-agent-i18n-setup).

## Related questions

- [Можно ли делать i18n без файлов перевода?](https://generaltranslation.com/ru/kb/i18n-without-translation-files.mdx): Да. Библиотеки gt-react и gt-next от General Translation обеспечивают i18n для React и Next.js без ключей перевода и без отдельного JSON-файла для каждого языка, который приходится поддерживать. Тексты остаются встроенными в JSX внутри компонента `<T>`, а команда gt translate генерирует переводы для каждого языка во время сборки, учитывая контекст из вашего кода. Locadex может поддерживать их в актуальном состоянии через пул-реквесты.
- [Как интернационализировать приложение с помощью Cursor или Claude Code?](https://generaltranslation.com/ru/kb/ai-agent-i18n-setup.mdx): Начните с промпта Setup for Agents от General Translation в Cursor или Claude Code, выберите функциональность и целевые языки, а затем поручите агенту реализовать и проверить результат. Вход через браузер, машиночитаемая документация и инструменты MCP связывают настройку с переводом и проверкой. Используйте Locadex, чтобы автоматизировать дальнейшую локализацию через пул-реквесты.
- [Как поддерживать переводы в актуальном состоянии при каждом развёртывании?](https://generaltranslation.com/ru/kb/translations-in-ci.mdx): Запускайте перевод как этап конвейера перед каждой сборкой для рабочей среды — тогда новые тексты попадут в то же развёртывание, что и сами изменения, уже переведёнными. В CLI gt от General Translation для этого служит команда npx gt translate, которая использует ключ API проекта и идентификатор проекта, сохранённые как секреты CI.

## Previous and next questions

- Previous question: [Что проверить перед запуском многоязычного приложения?](https://generaltranslation.com/ru/kb/multilingual-app-launch-checklist.mdx)
- Next question: [Как интернационализировать приложение с помощью Cursor или Claude Code?](https://generaltranslation.com/ru/kb/ai-agent-i18n-setup.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/ru/kb/sitemap.md) for every article.