Middleware

Descripción general

Esta guía te llevará paso a paso para agregar enrutamiento de middleware i18n y rutas localizadas a tu aplicación Next.js utilizando el middleware incorporado de gt-next.

¿Qué es el enrutamiento de middleware i18n?

Crear nuevas rutas para cada idioma tiene la ventaja de hacer tu sitio web más fácil de usar y mejorar el SEO. El enrutamiento i18n te permite asociar URLs específicas con diferentes configuraciones regionales. Por ejemplo, puedes tener /en/airplanes para inglés, /zh/airplanes para chino, y así sucesivamente.

Puedes llevar esto un paso más allá con rutas localizadas. Estas son una extensión del enrutamiento i18n que te permite especificar una ruta alias para una configuración regional. Por ejemplo, puedes especificar /en/airplanes para inglés, /zh/飞机 para chino, y así sucesivamente.

Configura el enrutamiento i18n

Te guiaremos a través de dos sencillos pasos para agregar enrutamiento i18n a tu aplicación Next.js:

Paso 1: Agrega una ruta dinámica

Inserta un directorio en tu carpeta app llamado [locale] (por ejemplo, app/[locale]). Incluye todas tus páginas y diseños dentro de este directorio.

Asegúrate de que todos los archivos especiales dentro de app/ estén anidados bajo app/[locale].

Paso 2: Agrega el archivo de middleware

En Next.js, crea un archivo llamado middleware.js (o .ts si estás usando TypeScript) dentro del directorio raíz. Si estás usando la carpeta src/, colócalo en src/middleware.js (o .ts) en su lugar. Agrega la función createNextMiddleware() al archivo.

import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    /*
      * Match all request paths except for the ones starting with:
      * - api (API routes)
      * - _next (internal files)
      * - static files
      */
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

Configura rutas localizadas

Puedes especificar rutas localizadas mediante la opción pathConfig en el archivo de middleware.

export default createNextMiddleware({
  pathConfig: {
    // You can specify a shared path (optional)
    // This will create "/en/about" and "/zh/about"
    "/about": "/about",

    // Specify localized paths
    // This will create "/en/airplanes" and "/zh/飞机"
    "/airplanes": {
      "zh": "/飞机",
    }

    // Add dynamic path parameters
    // This will create "/en/airports/123" and "/zh/飞机机场/123"
    "/airports/[id]": {
      "zh": "/飞机机场/[id]",
    }
  },
});

En este ejemplo creamos una ruta predeterminada para /en/about y rutas localizadas para /en/airplanes y /en/airports/[id]. En chino, estas se asignarán respectivamente a /zh/about, /zh/飞机 y /zh/飞机机场/[id].

Comportamiento de enrutamiento

Prefijado de la configuración regional por defecto

Por defecto, tu defaultLocale (es decir, el idioma predeterminado de tu aplicación) no se antepondrá con un código de configuración regional en la url. Por ejemplo, si tu configuración regional predeterminada es en y tienes una página en /about, será accesible en /about en inglés. Sin embargo, en chino, será accesible en /zh/about en chino.

Si no deseas este comportamiento, puedes desactivarlo estableciendo prefixDefaultLocale en false en la configuración del middleware.

Detección y redirección de la configuración regional

El middleware detectará la configuración regional del usuario basándose en (1) la configuración regional en la ruta de la url, (2) la configuración regional del referente, (3) los idiomas aceptados por el navegador y (4) finalmente el defaultLocale. Luego, el usuario será redirigido en consecuencia.

Si en cualquier momento existe una versión localizada de la página, serán redirigidos a la url localizada. Por ejemplo, /zh/airplanes siempre redirigirá a /zh/飞机.

Caso especial: rutas localizadas sin prefijo de configuración regional

Si navegas a una ruta localizada sin el prefijo de configuración regional (por ejemplo, /飞机), el middleware antepondrá ese camino con lo que considere que es tu configuración regional actual.

Por ejemplo, visitar /飞机 solo redirigirá a /zh/飞机 si el middleware reconoce explícitamente tu configuración regional como zh. Esto es útil, pero solo funciona cuando el middleware considera que tu configuración regional es zh.

De lo contrario, tu ruta será antepuesta con tu configuración regional actual. Por ejemplo, visitar /飞机 redirigirá a /en/飞机 si el middleware considera que tu configuración regional es en. Esto resultará en un error 404.

Recomendamos usar siempre la ruta de tu defaultLocale para cualquier enlace en tu proyecto. Esto siempre redirigirá automáticamente a la ruta localizada correcta.

<Link href="/about">About</Link>
<Link href="/planes">Planes</Link>
<Link href="/airports/123">Airport 123</Link>

Si deseas enlazar explícitamente a una configuración regional diferente, puedes hacerlo usando la ruta localizada.

<Link href="/zh/about">About in Chinese</Link>
<Link href="/zh/飞机">Planes in Chinese</Link>
<Link href="/zh/飞机机场/123">Airport 123 in Chinese</Link>

Notas

• El enrutamiento i18n cambia la estructura de URL de tu aplicación. Cada idioma tiene su propia URL.
• El archivo middleware es necesario para manejar la lógica de enrutamiento.
• Puedes especificar los locales soportados en la configuración de middleware y en el archivo de configuración de next.

Próximos pasos

• Consulta la documentación de la API para createNextMiddleware().