# node: Быстрый старт Node.js
URL: https://generaltranslation.com/ru/docs/node/tutorials/quickstart.mdx
---
title: Быстрый старт Node.js
description: Добавьте поддержку нескольких языков на свой сервер Node.js менее чем за 10 минут
---

После выполнения этого руководства ваш сервер Node.js будет возвращать переведённое содержимое в зависимости от языка запроса, используя либо инлайн, либо предварительно зарегистрированные строки.

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

* Сервер Node.js (Express, Fastify или аналогичный)
* Node.js 18+

<Callout type="info">
  **Нужен автоматический сетап?** Запустите `npx gt@latest`, чтобы настроить всё с помощью [мастера Setup](/docs/cli/init). В этом руководстве рассматривается ручная настройка.
</Callout>

***

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

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

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

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

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

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

***

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

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

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"]
}
```

* **`defaultLocale`** — язык, на котором написаны строки на вашем сервере.
* **`locales`** — языки, на которые вы хотите переводить. Выберите любые из [списка поддерживаемых локалей](/docs/platform/supported-locales).

***


## Шаг 3: Инициализируйте General Translation

Вызовите **`initializeGT`** один раз в начале входного файла сервера, прежде чем использовать какие-либо функции перевода:

```js title="server.js"
import { initializeGT } from 'gt-node';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```

Здесь вы настраиваете библиотеку, указывая поддерживаемые языки и учетные данные проекта.

***


## Шаг 4: Задайте контекст локали для каждого запроса

Каждому запросу нужно знать, какой язык использовать. Оберните обработчики запросов с помощью **`withGT`** — он использует асинхронное локальное хранилище, поэтому функции перевода автоматически подхватывают нужную локаль:

```js title="server.js"
import { withGT } from 'gt-node';

app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});
```

***


## Шаг 5: Перевод инлайн-строк

Чтобы переводить строки прямо внутри обработчиков запросов, используйте **`getGT`**:

```js title="server.js"
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({
    message: gt('Hello, world!'),
    welcome: gt('Welcome, {name}!', { name: 'Alice' }),
  });
});
```

`getGT` возвращает функцию перевода для локали текущего запроса.

***


## Шаг 6: Предварительно зарегистрируйте константные строки (необязательно)

Для строк, определённых вне обработчиков запросов, — например, сообщений об ошибках, меток перечислений или констант — используйте **`msg`** для регистрации на уровне модуля, а затем **`getMessages`** для получения переводов во время выполнения:

```js title="messages.js"
import { msg } from 'gt-node';

export const GREETING = msg('Hello, world!');
export const WELCOME = msg('Welcome, {name}!');
export const NOT_FOUND = msg('Resource not found.');
```

```js title="handler.js"
import { getMessages } from 'gt-node';
import { GREETING, WELCOME, NOT_FOUND } from './messages.js';

app.get('/api/status', async (req, res) => {
  const m = await getMessages();
  res.json({
    greeting: m(GREETING),
    welcome: m(WELCOME, { name: 'Alice' }),
  });
});

app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});
```

Этот подход полезен, когда одни и те же строки используются в нескольких обработчиках.

***


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

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

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

```bash title=".env"
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">
  Никогда не публикуйте `GT_API_KEY` и не коммитьте его в систему контроля версий.
</Callout>

<Accordions>
  <Accordion title="Можно ли использовать gt-node без API-ключей?">
    Да. Без API-ключей `gt-node` работает как обычная библиотека i18n. Перевод по запросу во время разработки будет недоступен, но вы по-прежнему можете:

    * Вручную добавлять собственные файлы переводов
    * Использовать все функции перевода (`getGT`, `msg`, `getMessages` и т. д.)
    * Запустить `npx gt generate`, чтобы создать шаблоны файлов перевода, а затем перевести их самостоятельно
  </Accordion>
</Accordions>

***


## Шаг 8: Проверка в работе

Запустите сервер и протестируйте его с разными заголовками `Accept-Language`:

```bash
# По умолчанию (английский)
curl http://localhost:3000/api/greeting

# Испанский
curl -H "Accept-Language: es" http://localhost:3000/api/greeting

# Французский
curl -H "Accept-Language: fr" http://localhost:3000/api/greeting
```

Вы должны увидеть переведённые ответы для каждого языка.

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

***


## Шаг 9: Полный пример

Вот полный пример сервера Express, где всё собрано вместе:

```js title="server.js"
import express from 'express';
import { initializeGT, withGT, getGT, msg, getMessages } from 'gt-node';

// Инициализировать GT раньше всего остального
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});

// Предварительная регистрация константных строк
const NOT_FOUND = msg('Resource not found.');

const app = express();

// Установить контекст локали для каждого запроса
app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});

// Инлайн-перевод
app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, world!') });
});

// Перевод предварительно зарегистрированного сообщения
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

***


## Шаг 10: Развертывание в продакшен

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

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

Задайте переменные окружения для **продакшен** у своего хостинг-провайдера:

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

<Callout type="warn">
  Никогда не публикуйте свой `GT_API_KEY` в открытом доступе.
</Callout>

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

***


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

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

  <Accordion title="Некоторые переводы неточны">
    Неоднозначный текст может приводить к неточным переводам. Например, &quot;apple&quot; может означать как фрукт, так и компанию. Чтобы уточнить значение, добавьте параметр `$context`:

    ```js
    gt('Apple', { $context: 'the technology company' });
    ```

    Параметр `$context` поддерживается и в `getGT()`, и в `msg()`.
  </Accordion>
</Accordions>

***

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

* [**`initializeGT`**](/docs/node/api/initialize-gt) — Полный список параметров конфигурации
* [**`withGT`**](/docs/node/api/with-gt) — Контекст локали в запросах
* [**`getGT`**](/docs/node/api/get-gt) — Инлайн-перевод строк
* [**`msg` &amp; `getMessages`**](/docs/node/api/get-messages) — Перевод предварительно зарегистрированных сообщений
* [**CLI**](/docs/cli/translate) — Справка по процессу перевода