# General Translation React SDKs (gt-react, gt-next, gt-react-native): Быстрый старт Next.js Pages Router
URL: https://generaltranslation.com/ru/docs/react/nextjs-pages-router-quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Добавьте поддержку нескольких языков в приложение Next.js на Pages Router с помощью General Translation менее чем за 10 минут.

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

В Pages Router `gt-next` работает через `getServerSideProps`: при каждом запросе сервер определяет локаль пользователя, загружает снимок переводов и передаёт их в [`<GTProvider>`](/docs/react/reference/components/gt-provider) в `_app.tsx`, чтобы содержимое уже при первом рендере было переведено.

Точка входа `gt-next/server` предназначена только для App Router и не работает с Pages Router.

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

* Приложение Next.js, использующее **Pages Router** (Next.js 13.0.0 или более поздней версии, кроме 15.2.1 и 15.2.2)
* Node.js 18+

<Callout type="info">
  **Примечание:** Если вы используете App Router, вместо этого следуйте руководству [Быстрый старт Next.js App Router](/docs/react/nextjs-quickstart). В нём используются серверные компоненты, и настройка `getServerSideProps` не требуется.
</Callout>

## Быстрый старт [#quickstart]

### 1. Установите пакеты

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

<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. Создайте файл конфигурации перевода

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

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

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

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

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

### 3. Настройте интернационализированную маршрутизацию в Next.js

Pages Router использует [интернационализированную маршрутизацию Next.js](https://nextjs.org/docs/pages/guides/internationalization) для URL-адресов с префиксом локали и определения локали запроса. Импортируйте настройки локали в `next.config.ts`, затем оберните конфигурацию с помощью `withGTConfig`:

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

const nextConfig: NextConfig = {
  i18n: {
    locales: gtConfig.locales,
    defaultLocale: gtConfig.defaultLocale,
  },
};

export default withGTConfig(nextConfig);
```

Next.js использует `/` для локали по умолчанию и добавляет префиксы к другим локалям, например `/es` и `/fr`. Middleware `gt-next` и сегмент маршрута `pages/[locale]` не нужны. Подробнее об определении локали и миграции см. в разделе [Маршрутизация по локалям в Pages Router](/docs/react/nextjs/pages-router-middleware).

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

Создайте файл **[`loadTranslations`](/docs/react/reference/functions/load-translations)** в корне проекта (или в каталоге `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 {};
  }
}
```

<Callout type="info">
  **Примечание:** Эти файлы перевода появятся только после того, как вы создадите их с помощью [`npx gt generate`](/docs/cli/reference/commands/generate) (ключ API не нужен) или [`npx gt translate`](/docs/cli/reference/commands/translate) (с учётными данными). До этого bundler будет предупреждать об отсутствии каталога `public/_gt`, а приведённый выше `try`/`catch` возвращает `{}`, поэтому приложение продолжает работать с непереведённым контентом.
</Callout>

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

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

### 5. Оберните getServerSideProps на страницах

Оберните `getServerSideProps` каждой страницы в **`withGTServerSideProps`**. При каждом запросе он считывает локаль, которую Next.js определил в `context.locale`, загружает снимок переводов для этой локали и передаёт и то и другое в пропсы страницы:

```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`](/docs/react/reference/components/gt-provider)** даёт всему приложению доступ к переводам. В `_app.tsx` извлеките внедрённые пропсы из `pageProps` и передайте их в провайдер. Тип **`WithGTServerSideProps`** описывает внедрённую структуру:

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

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

  return (
    <GTProvider
      locale={locale}
      translations={translations}
      _reload={({ locale: nextLocale }) => {
        void Router.push(Router.pathname, Router.asPath, {
          locale: nextLocale,
        });
      }}
    >
      <Component {...pageProps} />
    </GTProvider>
  );
}
```

Поскольку локаль и переводы приходят вместе с ответом сервера, уже при первом рендере интерфейс отображается на языке пользователя — без client-side loading state. Callback `_reload` передаёт изменения локали маршрутизатору Next.js, чтобы он загружал пропсы страницы выбранной локали.

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

Теперь оберните любой текст, который нужно перевести, в компонент **[`<T>`](/docs/react/reference/components/t)**. [`<T>`](/docs/react/reference/components/t) означает &quot;translate&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>`](/docs/react/reference/components/t) столько JSX, сколько захотите. Всё, что находится внутри — текст, вложенные элементы и даже форматирование, — переводится как единое целое.

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

Добавьте **[`<LocaleSelector>`](/docs/react/reference/components/locale-selector)**, чтобы пользователи могли переключать язык:

```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`](/docs/react/reference/components/locale-selector) отображает выпадающий список с языками из вашего `gt.config.json`. Когда пользователь выбирает язык, callback в `_app.tsx` перенаправляет на локализованный URL, а Next.js сохраняет этот выбор в cookie-файл `NEXT_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/en-US/signin) или выполнив команду:

```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">
  **Примечание:** В режиме разработки переводы выполняются по запросу, поэтому при первом переключении на новый язык вы можете ненадолго увидеть состояние загрузки. В продакшене переводы генерируются заранее и загружаются мгновенно.
</Callout>

### 11. Переводите строки, а не только JSX

Для обычных строк — например, атрибутов `placeholder`, значений `aria-label` или текста `alt` — используйте **[хук `useGT`](/docs/react/reference/hooks/use-gt)**:

```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>

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

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

<Accordions>
  <Accordion title="Нужен ли `withGTServerSideProps` на каждой странице?">
    Да — [`<GTProvider>`](/docs/react/reference/components/gt-provider) требует пропсы `locale` и `translations`, и они доступны только на страницах, где обёрнут `getServerSideProps`. Для страниц, которые не загружают собственные данные, экспортируйте вариант без аргументов:

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

  <Accordion title="Можно ли вместо этого использовать `getStaticProps`?">
    Да. Оберните страницу с помощью `withGTStaticProps` и продолжайте передавать сгенерированные пропсы в [`GTProvider`](/docs/react/reference/components/gt-provider) в `_app.tsx`. Полную настройку см. в [руководстве по Static Site Generation для Pages Router](/docs/react/nextjs/pages-router-static-site-generation).
  </Accordion>

  <Accordion title="Язык не меняется, когда я использую выпадающий список">
    Убедитесь, что `_reload` вызывает `Router.push` с выбранной опцией `locale`, как показано выше. После выбора URL должен содержать префикс локали, а cookie-файл `NEXT_LOCALE` — эту локаль.
  </Accordion>

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

## 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.