# gt-next: General Translation Next.js SDK: Краткое руководство по Pages Router
URL: https://generaltranslation.com/ru/docs/next/tutorials/quickstart-pages-router.mdx
---
title: Краткое руководство по Pages Router
description: Добавьте несколько языков в приложение Next.js с Pages Router менее чем за 10 минут
---

К концу этого руководства ваше приложение Next.js с Pages Router будет отображать контент на нескольких языках, а пользователи смогут переключать язык.

В Pages Router `gt-next` работает через `getServerSideProps`: при каждом запросе сервер определяет локаль пользователя, загружает снимок переводов и передаёт их в `<GTProvider>` в `_app.tsx`, поэтому первый рендер уже содержит переведённый контент.

**Предварительные требования:**

* Приложение Next.js, использующее **Pages Router**
* Node.js 18+

<Callout type="info">
  **Используете App Router?** Вместо этого воспользуйтесь [кратким руководством по Next.js](/docs/next) — в нём используются серверные компоненты и не требуется настройка `getServerSideProps`.
</Callout>

***

## Шаг 1: Установите пакеты

`gt-next` — это библиотека, которая обеспечивает переводы в вашем приложении. `gt` — это CLI-инструмент, который подготавливает переводы для продакшена.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-next
    npm i -D gt
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-next
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-next
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-next
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

***

## Шаг 2: Настройте конфигурацию Next.js

`gt-next` использует плагин Next.js под названием **`withGTConfig`** для настройки интернационализации на этапе сборки. Оберните им существующую конфигурацию Next.js:

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

const nextConfig = {};

export default withGTConfig(nextConfig);
```

Этот плагин считывает ваши настройки перевода и автоматически связывает всё воедино. Конфигурация одинакова для App Router и Pages Router — специальные флаги для роутера не нужны.

***

## Шаг 3: Создайте файл конфигурации перевода

Создайте файл **`gt.config.json`** в корне проекта. В нём библиотеке указывается, какие языки вы поддерживаете:

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

* **`defaultLocale`** — язык, на котором написано ваше приложение (исходный язык).
* **`locales`** — языки, на которые вы хотите переводить приложение. Выберите любые из [списка поддерживаемых локалей](/docs/platform/supported-locales).
* **`files.gt.output`** — путь, по которому CLI сохраняет файл перевода. `[locale]` заменяется кодом соответствующего языка (например, `public/_gt/es.json`).

Добавьте `public/_gt/` в **`.gitignore`** — эти файлы генерируются автоматически, а не создаются вручную:

```txt title=".gitignore"
public/_gt/
```

***

## Шаг 4: Добавьте функцию загрузки для локальных переводов

Создайте файл **`loadTranslations`** в корне проекта (или в каталоге `src/`). Это подскажет `gt-next`, как загружать файлы перевода, созданные CLI:

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

`withGTConfig` автоматически обнаруживает файл `loadTranslations.[js|ts]` в корне проекта или в каталоге `src/` — никакой дополнительной настройки не требуется.

<Callout type="info">
  **Почему локальные переводы?** Локальные переводы входят в сборку приложения, поэтому загружаются мгновенно и не зависят от внешних сервисов. Подробнее о преимуществах и компромиссах см. в [руководстве по локальному хранению переводов](/docs/next/guides/local-tx).
</Callout>

***

## Шаг 5: Оберните getServerSideProps на страницах

Оберните `getServerSideProps` каждой страницы с помощью **`withGTServerSideProps`**. При каждом запросе она определяет локаль пользователя — из cookie-файла `generaltranslation.locale`, если он задан, а в противном случае из заголовка `Accept-Language`, — загружает снимок переводов для этой локали и добавляет и то и другое в пропсы страницы:

```tsx title="pages/index.tsx"
import type { GetServerSideProps } from 'next';
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps: GetServerSideProps = withGTServerSideProps(
  async (context) => {
    return {
      props: {
        // ваши пропсы
      },
    };
  }
);
```

Если странице не требуются собственные серверные пропсы, вызовите её без аргументов:

```tsx title="pages/about.tsx"
import { withGTServerSideProps } from 'gt-next';

export const getServerSideProps = withGTServerSideProps();
```

`withGTServerSideProps` добавляет `locale` и `translations` в ваш пропс (а также внутренний флаг `enableI18n`). Если внутренняя функция возвращает `redirect` или `notFound`, результат передаётся дальше без изменений, без загрузки переводов.

***

## Шаг 6: Добавьте GTProvider в приложение

Компонент **`GTProvider`** даёт всему приложению доступ к переводам. В `_app.tsx` извлеките внедрённые пропсы из `pageProps` и передайте их в провайдер. Тип **`WithGTServerSideProps`** описывает внедрённую структуру:

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import { GTProvider, WithGTServerSideProps } from 'gt-next';

export default function App({
  Component,
  pageProps,
}: AppProps<WithGTServerSideProps>) {
  const { locale, translations, ...restPageProps } = pageProps;

  return (
    <GTProvider locale={locale} translations={translations}>
      <Component {...restPageProps} />
    </GTProvider>
  );
}
```

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

***

## Шаг 7: Пометьте текст для перевода

Теперь оберните любой текст, который хотите перевести, в компонент **`<T>`**. `<T>` означает &quot;перевести&quot;:

```tsx title="pages/index.tsx"
import { T } from 'gt-next';

export default function Home() {
  return (
    <main>
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

Вы можете обернуть в `<T>` сколько угодно JSX. Всё внутри него — текст, вложенные элементы и даже форматирование — переводится как единое целое.

***

## Шаг 8: Добавьте переключатель языка

Добавьте **`<LocaleSelector>`**, чтобы пользователи могли переключать язык:

```tsx title="pages/index.tsx"
import { T, LocaleSelector } from 'gt-next';

export default function Home() {
  return (
    <main>
      <LocaleSelector />
      <T>
        <h1>Welcome to my app</h1>
        <p>This content will be translated automatically.</p>
      </T>
    </main>
  );
}
```

`LocaleSelector` отображает выпадающий список с языками из вашего файла `gt.config.json`. Когда пользователь выбирает язык, `gt-next` сохраняет этот выбор в cookie-файле `generaltranslation.locale` и перезагружает страницу, чтобы сервер заново отрисовал всё в новой локали.

***

## Шаг 9: Настройте переменные окружения (необязательно)

Чтобы видеть переводы во время разработки, вам понадобятся API-ключи General Translation. Они позволяют использовать **перевод по запросу** — приложение будет переводить контент в реальном времени по мере разработки.

Создайте файл **`.env.local`**:

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

Получите бесплатные ключи на [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) или выполнив команду:

```bash
npx gt auth
```

<Callout type="warn">
  Для разработки используйте ключ с префиксом `gtx-dev-`. Рабочие ключи (`gtx-api-`) предназначены только для CI/CD.

  Никогда не передавайте `GT_API_KEY` в браузер и не коммитьте его в систему контроля версий.
</Callout>

***

## Шаг 10: Посмотрите, как это работает

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

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm run dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn dev
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun dev
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm dev
    ```
  </Tab>
</Tabs>

Откройте [http://localhost:3000](http://localhost:3000) и используйте выпадающий список языков, чтобы переключаться между ними. Вы увидите переведённый контент.

<Callout type="info">
  Во время разработки переводы выполняются по запросу — при первом переключении на новый язык вы можете ненадолго увидеть состояние загрузки. В Production переводы генерируются заранее и загружаются мгновенно.
</Callout>

***

## Шаг 11: Переводите строки (не только JSX)

Для обычных строк — таких как атрибуты `placeholder`, значения `aria-label` или текст `alt` — используйте хук **`useGT`**:

```tsx title="pages/contact.tsx"
import { useGT } from 'gt-next';

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

  return (
    <form>
      <input
        placeholder={gt('Enter your email')}
        aria-label={gt('Email input field')}
      />
      <button type="submit">{gt('Send')}</button>
    </form>
  );
}
```

***

## Шаг 12: Развертывание в production

В production переводы генерируются заранее на этапе сборки (без API-вызовов в реальном времени). Добавьте команду translate в скрипт сборки:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && next build"
  }
}
```

Настройте переменные окружения для **production** у вашего хостинг-провайдера (Vercel, Netlify и т. д.):

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

<Callout type="warn">
  Рабочие ключи начинаются с `gtx-api-` (не с `gtx-dev-`). Получить такой ключ можно на [dash.generaltranslation.com](https://dash.generaltranslation.com). Никогда не добавляйте к нему префикс `NEXT_PUBLIC_`.
</Callout>

Вот и всё — теперь ваше приложение стало многоязычным. 🎉

***

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

<Accordions>
  <Accordion title="Нужен ли withGTServerSideProps на каждой странице?">
    Да — `<GTProvider>` требует пропсы `locale` и `translations`, а они доступны только на страницах, где `getServerSideProps` обёрнут этой функцией. Для страниц, которые не загружают собственные данные, экспортируйте вариант без аргументов:

    ```tsx
    export const getServerSideProps = withGTServerSideProps();
    ```
  </Accordion>

  <Accordion title="Можно ли использовать getStaticProps вместо этого?">
    Нет. Для определения локали нужны данные per-request (cookie-файл локали и header `Accept-Language`), а они недоступны при статической генерации. `gt-next` не предоставляет хелпер `getStaticProps` для Pages Router.
  </Accordion>

  <Accordion title="Язык не меняется, когда я использую выпадающий список">
    `gt-next` сохраняет языковые предпочтения пользователя в 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)
  </Accordion>

  <Accordion title="В development переводы работают медленно">
    Это ожидаемо. В development переводы выполняются по запросу (ваш контент переводится в реальном времени через API). Эта задержка **не возникает в production** — все переводы заранее генерируются командой `npx gt translate`.
  </Accordion>
</Accordions>

***

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

* [**Руководство по компоненту `<T>`**](/docs/next/guides/t) — Узнайте больше о переменных, формах множественного числа и продвинутых шаблонах перевода
* [**Руководство по переводу строк**](/docs/next/guides/strings) — Подробный разбор `useGT`
* [**Компоненты переменных**](/docs/next/guides/variables) — Работайте с динамическим контентом с помощью `<Var>`, `<Num>`, `<Currency>` и `<DateTime>`
* [**Плюрализация**](/docs/next/api/components/plural) — Обрабатывайте формы множественного числа с помощью компонента `<Plural>`
* [**Развертывание в Production**](/docs/next/tutorials/quickdeploy) — Настройка CI/CD, кэширования и оптимизация производительности
* [**Общие строки**](/docs/next/guides/shared-strings) — Переводите текст в массивах, объектах конфигурации и общих данных с помощью `msg()`