# node: Определение локали и middleware
URL: https://generaltranslation.com/ru/docs/node/guides/middleware.mdx
---
title: Определение локали и middleware
description: Как определить локаль пользователя и задать её для каждого запроса с помощью withGT
---

Каждая функция перевода в `gt-node` должна знать, для какой локали обрабатывается текущий запрос. [`withGT`](/docs/node/api/with-gt) задаёт этот контекст через async local storage — оберните handler запроса, и все последующие вызовы перевода автоматически будут использовать нужную локаль.

## Как работает `withGT`

`withGT` принимает строку локали и колбэк. Внутри этого колбэка [`getGT()`](/docs/node/api/get-gt), [`getMessages()`](/docs/node/api/get-messages) и [`getLocale()`](/docs/node/api/get-locale) используют заданную вами локаль:

```js
import { withGT, getLocale } from 'gt-node';

app.use((req, res, next) => {
  const locale = detectLocale(req);
  withGT(locale, () => next());
});
```

<Callout type="warn">
  Функции перевода, вызванные вне контекста `withGT`, будут использовать `defaultLocale`. Всегда оборачивайте код обработки запросов в `withGT`.
</Callout>


## Способы определения локали

### Заголовок Accept-Language

Используйте [`getRequestLocale`](/docs/node/api/get-request-locale), чтобы разобрать заголовок `Accept-Language` и сопоставить его с локалями, настроенными в конфигурации:

```js
import { getRequestLocale } from 'gt-node';

function detectLocale(req) {
  return getRequestLocale(req);
}
```

`getRequestLocale` автоматически обрабатывает q-значения, записи с масками и сопоставление языка и региона.

### Через cookie

Сохраняйте выбранный пользователем язык между сеансами:

```js
import cookieParser from 'cookie-parser';
app.use(cookieParser());

function detectLocale(req) {
  return req.cookies.locale || 'en';
}

// Эндпоинт для установки языковых предпочтений
app.post('/api/set-language', (req, res) => {
  res.cookie('locale', req.body.locale, { maxAge: 365 * 24 * 60 * 60 * 1000 });
  res.json({ ok: true });
});
```


### Параметр URL

Извлекает локаль из URL-пути (например, `/es/api/greeting`):

```js
function detectLocale(req) {
  const segments = req.path.split('/').filter(Boolean);
  const supported = new Set(['es', 'fr', 'ja', 'de']);
  if (segments[0] && supported.has(segments[0])) {
    return segments[0];
  }
  return 'en';
}
```


### Параметр строки запроса

Используйте параметр строки запроса `?lang=`:

```js
function detectLocale(req) {
  return req.query.lang || 'en';
}
```


## Комбинирование стратегий

На практике стоит пробовать несколько стратегий в порядке приоритета:

```js
function detectLocale(req) {
  // 1. Явный параметр строки запроса (наивысший приоритет)
  if (req.query.lang) return req.query.lang;

  // 2. Cookie (сохранённые настройки пользователя)
  if (req.cookies?.locale) return req.cookies.locale;

  // 3. Заголовок Accept-Language (браузерное значение по умолчанию)
  const acceptLang = req.headers['accept-language']?.split(',')[0];
  if (acceptLang) return acceptLang;

  // 4. По умолчанию
  return 'en';
}
```

## Middleware для Express

Полная настройка middleware для Express:

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

export function localeMiddleware(req, res, next) {
  const locale =
    req.query.lang ||
    req.cookies?.locale ||
    req.headers['accept-language']?.split(',')[0] ||
    'en';

  withGT(locale, () => next());
}
```

```js title="server.js"
import express from 'express';
import cookieParser from 'cookie-parser';
import { initializeGT } from 'gt-node';
import { localeMiddleware } from './middleware/locale.js';

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

const app = express();
app.use(cookieParser());
app.use(localeMiddleware);
```


## Middleware в Fastify

Тот же подход можно использовать и в Fastify через Hook `preHandler`:

```js title="server.js"
import Fastify from 'fastify';
import cookie from '@fastify/cookie';
import { initializeGT, withGT, getGT } from 'gt-node';

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

const app = Fastify();
await app.register(cookie);

app.addHook('preHandler', (req, reply, done) => {
  const locale =
    req.query.lang ||
    req.cookies?.locale ||
    req.headers['accept-language']?.split(',')[0] ||
    'en';

  withGT(locale, () => done());
});

app.get('/api/greeting', async (req, reply) => {
  const gt = await getGT();
  return { message: gt('Hello, world!') };
});

app.listen({ port: 3000 });
```


## Чтение текущей локали

Используйте [`getLocale()`](/docs/node/api/get-locale) в любом месте в контексте `withGT`, чтобы получить определённую локаль:

```js
import { getLocale } from 'gt-node';

app.get('/api/info', async (req, res) => {
  const locale = getLocale();
  res.json({ currentLocale: locale });
});
```


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

* [`withGT` API справка](/docs/node/api/with-gt)
* [`getLocale` API справка](/docs/node/api/get-locale)
* [`getRequestLocale` API справка](/docs/node/api/get-request-locale)
* [Подходы к переводу строк](/docs/node/guides/strings) — как переводить содержимое
* [Локальное хранилище переводов](/docs/node/guides/local-tx) — включите переводы в бандл приложения