# 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 adecuada de tu sitio.
Usa la configuración del navegador, la geolocalización y las preferencias del usuario para mostrar el idioma correcto 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 a su interior:

<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: Agregar middleware

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

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

export default createNextMiddleware();

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

Esto habilita 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 configurado como alternativa

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

## Rutas localizadas

Personaliza las rutas 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

Por defecto, tu configuración regional predeterminada **no** llevará 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)
```


### Agregar un prefijo a la configuración regional predeterminada

Para agregar un prefijo a todos los locales, incluido el predeterminado:

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

Resultado:

```
/about     → /en/about     (inglés, con prefijo)
/about     → /es/about     (español, con prefijo)
/about     → /fr/about     (francés, con prefijo)
```


## Problemas comunes

### 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 la 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 mal configurados pueden causar redirecciones infinitas o romper los recursos estáticos.
</Callout>


## Próximos pasos

* [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 la API: