# node: Detección de la configuración regional y middleware
URL: https://generaltranslation.com/es/docs/node/guides/middleware.mdx
---
title: Detección de la configuración regional y middleware
description: Cómo detectar la configuración regional del usuario y establecerla para cada solicitud con withGT
---

Todas las funciones de traducción de `gt-node` necesitan saber a qué configuración regional apunta la solicitud actual. [`withGT`](/docs/node/api/with-gt) establece este contexto mediante almacenamiento local asíncrono: envuelve tu manejador de solicitud y todas las llamadas de traducción posteriores usarán automáticamente la configuración regional correcta.

## Cómo funciona `withGT`

`withGT` recibe una cadena de configuración regional y un callback. Dentro de ese callback, [`getGT()`](/docs/node/api/get-gt), [`getMessages()`](/docs/node/api/get-messages) y [`getLocale()`](/docs/node/api/get-locale) leen la configuración regional que hayas establecido:

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

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

<Callout type="warn">
  Las funciones de traducción que se llamen fuera de un contexto `withGT` usarán `defaultLocale`. Envuelve siempre el manejo de solicitudes en `withGT`.
</Callout>


## Estrategias para detectar la configuración regional

### Cabecera Accept-Language

Usa [`getRequestLocale`](/docs/node/api/get-request-locale) para analizar la cabecera `Accept-Language` y compararla con las configuraciones regionales que hayas definido:

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

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

`getRequestLocale` gestiona automáticamente los valores de calidad, las entradas comodín y la correspondencia entre idioma y configuración regional.

### Basado en cookies

Conserva la elección de idioma del usuario entre sesiones:

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

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

// Endpoint para establecer la preferencia de idioma
app.post('/api/set-language', (req, res) => {
  res.cookie('locale', req.body.locale, { maxAge: 365 * 24 * 60 * 60 * 1000 });
  res.json({ ok: true });
});
```


### Parámetro de URL

Extrae la configuración regional de la ruta de la URL (p. ej., `/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';
}
```


### Parámetro de consulta

Usa el parámetro de consulta `?lang=`:

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


## Estrategias de encadenamiento

En la práctica, conviene probar varias estrategias por orden de prioridad:

```js
function detectLocale(req) {
  // 1. Parámetro de consulta explícito (máxima prioridad)
  if (req.query.lang) return req.query.lang;

  // 2. Cookie (preferencia guardada del usuario)
  if (req.cookies?.locale) return req.cookies.locale;

  // 3. Encabezado Accept-Language (valor por defecto del navegador)
  const acceptLang = req.headers['accept-language']?.split(',')[0];
  if (acceptLang) return acceptLang;

  // 4. Valor por defecto
  return 'en';
}
```


## Middleware de Express

Una configuración completa de middleware para 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 de Fastify

El mismo pattern funciona en Fastify con un 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 });
```


## Leer la configuración regional actual

Usa [`getLocale()`](/docs/node/api/get-locale) en cualquier punto dentro de un contexto `withGT` para obtener la configuración regional resuelta:

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

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


## Siguientes pasos

* [`withGT` referencia de la API](/docs/node/api/with-gt)
* [`getLocale` referencia de la API](/docs/node/api/get-locale)
* [`getRequestLocale` referencia de la API](/docs/node/api/get-request-locale)
* [Patrones de traducción de cadenas](/docs/node/guides/strings) — cómo traducir contenido
* [Almacenamiento local de traducciones](/docs/node/guides/local-tx) — incluye traducciones en el bundle de tu app