# gt-next: General Translation Next.js SDK: Middleware
URL: https://generaltranslation.com/es/docs/next/guides/middleware.mdx
---
title: Middleware
description: Detección automática del idioma y enrutamiento de URL según las preferencias del usuario
---

Middleware detecta automáticamente las preferencias de idioma del usuario y lo redirige a la versión localizada correspondiente de tu sitio.
Usa la configuración del navegador, la geolocalización y las preferencias del usuario para mostrar el idioma adecuado antes de que se cargue cualquier contenido.

<Callout>
  **Ubicación del archivo:** Coloca `proxy.ts` en la raíz de tu proyecto, al mismo nivel que tu directorio `app/`, no dentro de él. `proxy.ts` (Next.js 16+) o `middleware.ts` (Next.js 15 y versiones anteriores)
</Callout>

## Configuración

### Paso 1: Crear una ruta dinámica

Crea un directorio `[locale]` en la carpeta `app/` y mueve todas las páginas dentro de él:

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <File name="proxy.ts" />

    <Folder name="app" defaultOpen={true}>
      <Folder name="[locale]" defaultOpen={true}>
        <File name="layout.tsx" />

        <File name="page.tsx" />

        <Folder name="about">
          <File name="page.tsx" />
        </Folder>
      </Folder>

      <Folder name="api">
        <File name="route.ts" />
      </Folder>
    </Folder>

    <File name="next.config.js" />
  </Folder>
</Files>

### Paso 2: Agrega el middleware

Crea `proxy.ts` en la raíz de tu proyecto:

```ts
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  // Coincide con todas las rutas excepto rutas de API, archivos estáticos e internos de Next.js
  matcher: ['/((?!api|static|.*\\..*|_next).*)']
};
```

Esto permite la detección automática del idioma y el enrutamiento de URL con prefijos de configuración regional como `/en/about`, `/es/about`.


## Detección de idioma

El middleware detecta las preferencias de idioma del usuario en este orden:

1. **Configuración regional de la URL** - `/es/about` → español
2. **cookie del usuario** - Selección de idioma previa
3. **Encabezados del navegador** - Encabezado `Accept-Language`
4. **Configuración regional predeterminada** - Idioma de respaldo configurado

El middleware gestiona automáticamente la detección del idioma del navegador y la persistencia de la cookie sin necesidad de configuración adicional.

## Rutas localizadas

Personaliza las rutas de las URL para diferentes idiomas:

```ts
export default createNextMiddleware({
  pathConfig: {
    // Inglés: /en/products, Chino: /zh/产品
    "/products": {
      "zh": "/产品"
    },
    
    // Rutas dinámicas: /en/product/123, /zh/产品/123
    "/product/[id]": {
      "zh": "/产品/[id]"
    }
  }
});
```


## Estructura de URL

De forma predeterminada, tu configuración regional predeterminada **no** tendrá como prefijo un código de configuración regional:

```
/about     → /about        (configuración regional predeterminada: inglés)
/about     → /es/about     (español)
/about     → /fr/about     (francés)
```


### Añadir un prefijo a la configuración regional predeterminada

Para añadir un prefijo a todas las configuraciones regionales, incluida la predeterminada:

```ts
export default createNextMiddleware({
  prefixDefaultLocale: true
});
```

Resultado:

```
/about     → /en/about     (English, with prefix)
/about     → /es/about     (Spanish, with prefix)
/about     → /fr/about     (French, with prefix)
```


## Problemas frecuentes

### Falta la ruta dinámica

Todas las páginas deben estar dentro de `[locale]/`:

```
❌ Wrong:
app/
├── page.tsx
└── about/page.tsx

✅ Correct:
app/
└── [locale]/
    ├── page.tsx
    └── about/page.tsx
```


### Configuración del matcher

Excluye las rutas de API y los archivos estáticos:

```ts
export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next).*)']
};
```

<Callout>
  Prueba a fondo la configuración de tu middleware: unos `matchers` incorrectos pueden causar redirecciones infinitas o hacer que los archivos estáticos dejen de funcionar.
</Callout>

## Próximos pasos

<Callout>
  **Véalo en acción:** La [aplicación de ejemplo de generación de sitios estáticos](https://github.com/gt-examples/static-site-generation) incluye una configuración completa del middleware con enrutamiento por configuración regional — [vista previa en vivo](https://static-site-generation.generaltranslation.dev).
</Callout>

* [Guía de SSG](/docs/next/guides/ssg) - Generación estática con enrutamiento por configuración regional
* [Compatibilidad con RTL](/docs/next/guides/rtl) - Idiomas de escritura de derecha a izquierda
* Referencias de API: