Enrutamiento de internacionalización (i18n)

Las características de internacionalización (i18n) de Astro te permiten adaptar tu proyecto para una audiencia internacional. Esta API de enrutamiento te ayuda a generar, usar y verificar las URLs que tu sitio multiidioma produce.

El enrutamiento i18n de Astro te permite traer tu contenido multilingüe con soporte para configurar un idioma predeterminado, calcular URLs relativas de páginas y aceptar los idiomas preferidos proporcionados por el navegador de tu visitante. También puedes especificar idiomas de fallback por cada idioma para que tus visitantes siempre sean dirigidos a contenido existente en tu sitio.

Lógica de enrutamiento

Astro usa un middleware para implementar su lógica de enrutamiento. Esta función de middleware se coloca en la primera posición donde espera cada Response proveniente de cualquier middleware adicional y de cada ruta de página antes de finalmente ejecutar su propia lógica.

Esto significa que las operaciones (p. ej. redirecciones) de tu propio middleware y la lógica de tus páginas se ejecutan primero, tus rutas se renderizan, y luego el middleware i18n realiza sus propias acciones como verificar que una URL localizada corresponde a una ruta válida.

También puedes elegir añadir tu propia lógica i18n además de o en lugar del middleware i18n de Astro, dándote aún más control sobre tus rutas mientras sigues teniendo acceso a las funciones helper de astro:i18n.

Configurar el enrutamiento i18n

En tu configuración de i18n, especifica la lista de todos los idiomas soportados (locales) y establece uno de ellos como el idioma predeterminado (defaultLocale). También puedes configurar un comportamiento de enrutamiento y fallback más específico para que coincida con las URLs deseadas.

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "pt-br"],
    defaultLocale: "en",
  }
})

Crear carpetas localizadas

Organiza tus carpetas de contenido con contenido localizado por idioma. Crea carpetas individuales /[locale]/ en cualquier lugar dentro de src/pages/ y el enrutamiento basado en archivos de Astro creará tus páginas en las rutas URL correspondientes.

Los nombres de tus carpetas deben coincidir exactamente con los elementos en locales. Incluye una carpeta localizada para tu defaultLocale solo si configuras prefixDefaultLocale: true para mostrar una ruta URL localizada para tu idioma predeterminado (p. ej. /en/about/).

Directoriosrc
- Directoriopages
  - about.astro
  - index.astro
  - Directorioes
    about.astro
    index.astro
  - Directoriopt-br
    about.astro
    index.astro

Crear enlaces

Con el enrutamiento i18n configurado, ahora puedes calcular enlaces a páginas dentro de tu sitio usando las funciones helper como getRelativeLocaleUrl() disponibles desde el módulo astro:i18n. Estos enlaces generados siempre proporcionarán la ruta localizada correcta y pueden ayudarte a usar o verificar correctamente las URLs en tu sitio.

También puedes seguir escribiendo los enlaces manualmente.

---
import { getRelativeLocaleUrl } from 'astro:i18n';

// defaultLocale is "es"
const aboutURL = getRelativeLocaleUrl("es", "about");
---

<a href="/get-started/">¡Vamos!</a>
<a href={getRelativeLocaleUrl('es', 'blog')}>Blog</a>
<a href={aboutURL}>Acerca</a>

`routing`

El enrutamiento basado en archivos integrado de Astro crea automáticamente rutas URL para ti basándose en tu estructura de archivos dentro de src/pages/.

Cuando configuras el enrutamiento i18n, la información sobre esta estructura de archivos (y las rutas URL correspondientes generadas) está disponible para las funciones helper de i18n para que puedan generar, usar y verificar las rutas en tu proyecto. Muchas de estas opciones se pueden usar juntas para aún más personalización y flexibilidad por idioma.

Incluso puedes elegir implementar tu propia lógica de enrutamiento manualmente para un mayor control.

`prefixDefaultLocale`

Añadido en: astro@3.5.0

Esta opción de enrutamiento define si las URLs de tu idioma predeterminado deben usar un prefijo de idioma (p. ej. /en/about/).

Todos los idiomas soportados que no sean el predeterminado usarán un prefijo localizado (p. ej. /fr/ o /french/) y los archivos de contenido deben ubicarse en las carpetas apropiadas. Esta opción de configuración te permite especificar si tu idioma predeterminado también debe seguir una estructura de URL localizada.

Este ajuste también determina dónde deben existir los archivos de página para tu idioma predeterminado (p. ej. src/pages/about/ o src/pages/en/about) ya que la estructura de archivos y la estructura de URL deben coincidir para todos los idiomas.

"prefixDefaultLocale: false" (predeterminado): Las URLs en tu idioma predeterminado no tendrán un prefijo /[locale]/. Todos los demás locales sí lo tendrán.
"prefixDefaultLocale: true": Todas las URLs, incluyendo tu idioma predeterminado, tendrán un prefijo /[locale]/.

`prefixDefaultLocale: false`

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
        prefixDefaultLocale: false
    }
  }
})

Este es el valor predeterminado. Establece esta opción cuando las URLs en tu idioma predeterminado no tengan un prefijo /[locale]/ y los archivos en tu idioma predeterminado existan en la raíz de src/pages/:

Directoriosrc
- Directoriopages
  - about.astro
  - index.astro
  - Directorioes
    about.astro
    index.astro
  - Directoriofr
    about.astro
    index.astro

src/pages/about.astro producirá la ruta example.com/about/
src/pages/fr/about.astro producirá la ruta example.com/fr/about/

`prefixDefaultLocale: true`

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: {
        prefixDefaultLocale: true
    }
  }
})

Establece esta opción cuando todas las rutas tengan su prefijo /locale/ en su URL y cuando todos los archivos de contenido de página, incluyendo los de tu defaultLocale, existan en una carpeta localizada:

Directoriosrc
- Directoriopages
  - index.astro // Nota: este archivo siempre es obligatorio
  - Directorioen
    index.astro
    about.astro
  - Directorioes
    about.astro
    index.astro
  - Directoriopt-br
    about.astro
    index.astro

Las URLs sin un prefijo de locale (p. ej. example.com/about/) devolverán un código de estado 404 (no encontrado) a menos que especifiques una estrategia de fallback.

Excluirse de las redirecciones para la URL de inicio

Incluso con las rutas de tu locale predeterminado prefijadas, este comportamiento no se aplica por defecto a la página de índice de tu sitio. Esto te permite tener una página de inicio que existe fuera de tu estructura de locales configurada, donde todas tus rutas localizadas están prefijadas excepto la URL de inicio de tu sitio.

Puedes excluirte de este comportamiento para que la URL principal de tu sitio también redirija a una ruta localizada prefijada para tu locale predeterminado. Cuando prefixDefaultLocale: true está establecido, puedes configurar adicionalmente redirectToDefaultLocale: true. Esto asegurará que la URL de inicio (/) generada por src/pages/index.astro redirija a /[defaultLocale]/.

`manual`

Añadido en: astro@4.6.0

Cuando esta opción está habilitada, Astro deshabilitará su middleware i18n para que puedas implementar tu propia lógica personalizada. No se pueden configurar otras opciones de routing (p. ej. prefixDefaultLocale) con routing: "manual".

Serás responsable de escribir tu propia lógica de enrutamiento, o ejecutar el middleware i18n de Astro manualmente junto con el tuyo propio.

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    routing: "manual"
  }
})

Astro proporciona funciones helper para tu middleware para que puedas controlar tu propio enrutamiento predeterminado, excepciones, comportamiento de fallback, captura de errores, etc: redirectToDefaultLocale(), notFound(), y redirectToFallback():

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n"; // function available with `manual` routing
export const onRequest = defineMiddleware(async (ctx, next) => {
  if (ctx.url.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(302);
  }
})

función de middleware

La función middleware() crea manualmente el middleware i18n de Astro. Esto te permite extender el enrutamiento i18n de Astro en lugar de reemplazarlo por completo.

Puedes ejecutar middleware() con opciones de enrutamiento en combinación con tu propio middleware, usando la utilidad sequence() para determinar el orden:

import { defineMiddleware, sequence } from "astro:middleware";
import { middleware } from "astro:i18n"; // Astro's own i18n routing config

export const userMiddleware = defineMiddleware(async (ctx, next) => {
  // this response might come from Astro's i18n middleware, and it might return a 404
  const response = await next();
  // the /about page is an exception and we want to render it
  if (ctx.url.pathname.startsWith("/about")) {
    return new Response("About page", {
      status: 200,
    });
  } else {
    return response;
  }
});

export const onRequest = sequence(
  userMiddleware,
  middleware({
    redirectToDefaultLocale: false,
    prefixDefaultLocale: true,
    fallbackType: "redirect",
  }),
);

`domains`

Añadido en: astro@4.9.0

Esta opción de enrutamiento te permite personalizar tus dominios por cada idioma para proyectos renderizados en el servidor usando el adaptador @astrojs/node o @astrojs/vercel con un site configurado.

Añade i18n.domains para mapear cualquiera de tus locales soportados a URLs personalizadas:

import { defineConfig } from "astro/config"
export default defineConfig({
  site: "https://example.com",
  output: "server", // required, with no prerendered pages
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    locales: ["es", "en", "fr", "ja"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: false
    },
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  }
})

Todos los locales no mapeados seguirán tu configuración de prefixDefaultLocales.

Con la configuración anterior:

El archivo /fr/about.astro creará la URL https://fr.example.com/about.
El archivo /es/about.astro creará la URL https://example.es/about.
El archivo /ja/about.astro creará la URL https://example.com/ja/about.
El archivo /about.astro creará la URL https://example.com/about.

Las URLs anteriores también serán devueltas por las funciones getAbsoluteLocaleUrl() y getAbsoluteLocaleUrlList().

Fallback

Cuando una página en un idioma no existe (p. ej. una página que aún no está traducida), en lugar de mostrar una página 404, puedes elegir mostrar contenido de fallback de otro locale por cada idioma. Esto es útil cuando aún no tienes una página para cada ruta, pero quieres proporcionar algo de contenido a tus visitantes.

Tu estrategia de fallback consta de dos partes: elegir qué idiomas deben hacer fallback a qué otros idiomas (i18n.fallback) y elegir si realizar una redirección o un rewrite para mostrar el contenido de fallback (i18n.routing.fallbackType añadido en Astro v4.15.0).

Por ejemplo, cuando configuras i18n.fallback: { fr: "es" }, Astro se asegurará de que se construya una página en src/pages/fr/ por cada página que exista en src/pages/es/.

Si alguna página no existe ya, entonces se creará una página dependiendo de tu fallbackType:

Con una redirección a la ruta es correspondiente (comportamiento predeterminado).
Con el contenido de la página /es/ (i18n.routing.fallbackType: "rewrite").

Por ejemplo, la configuración siguiente establece es como el locale de fallback para cualquier ruta fr faltante. Esto significa que un usuario que visite example.com/fr/my-page/ se le mostrará el contenido de example.com/es/my-page/ (sin ser redirigido) en lugar de ser llevado a una página 404 cuando src/pages/fr/my-page.astro no existe.

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    fallback: {
      fr: "es"
    },
    routing: {
      fallbackType: "rewrite"
    }
  }
})

Rutas de locale personalizadas

Además de definir los locales soportados de tu sitio como cadenas (p. ej. “en”, “pt-br”), Astro también te permite mapear un número arbitrario de códigos de idioma reconocidos por el navegador codes a una ruta URL personalizada. Mientras que los locales pueden ser cadenas de cualquier formato siempre que correspondan a la estructura de carpetas de tu proyecto, los codes deben seguir la sintaxis aceptada por el navegador.

Pasa un objeto al array locales con una clave path para definir un prefijo de URL personalizado, y codes para indicar los idiomas mapeados a esta URL. En este caso, el nombre de tu carpeta /[locale]/ debe coincidir exactamente con el valor del path y tus URLs se generarán usando el valor de path.

Esto es útil si soportas múltiples variaciones de un idioma (p. ej. "fr", "fr-BR", y "fr-CA") y quieres tener todas estas variaciones mapeadas bajo la misma URL /fr/, o incluso personalizarla por completo (p. ej. /french/):

import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    locales: ["es", "en", {
      path: "french", // no slashes included
      codes: ["fr", "fr-BR", "fr-CA"]
    }],
    defaultLocale: "en",
    routing: {
        prefixDefaultLocale: true
    }
  }
})

Cuando uses funciones del módulo virtual astro:i18n para calcular rutas URL válidas basadas en tu configuración (p. ej. getRelativeLocaleUrl()), usa el path como el valor para locale.

Limitaciones

Esta característica tiene algunas restricciones:

La opción site es obligatoria.
La opción output debe establecerse en "server".
No puede haber páginas prerenderizadas individuales.

Astro depende de los siguientes headers para soportar la característica:

X-Forwarded-Host y Host. Astro usará el primero, y si no está presente, intentará el segundo.
X-Forwarded-Proto y URL#protocol de la solicitud del servidor.

Asegúrate de que tu proxy de servidor/plataforma de hosting pueda proporcionar esta información. No poder recuperar estos headers resultará en una página 404 (código de estado).

Detección de idioma del navegador

El enrutamiento i18n de Astro te permite acceder a dos propiedades para la detección de idioma del navegador en páginas renderizadas bajo demanda: Astro.preferredLocale y Astro.preferredLocaleList. Todas las páginas, incluyendo las páginas estáticas prerenderizadas, tienen acceso a Astro.currentLocale.

Estas combinan el header Accept-Language del navegador, y tus locales (cadenas o codes) para respetar automáticamente los idiomas preferidos de tu visitante.

Astro.preferredLocale: Astro puede calcular un locale preferido para tu visitante si el locale preferido de su navegador está incluido en tu array de locales. Este valor es undefined si no existe tal coincidencia.
Astro.preferredLocaleList: Un array de todos los locales que son tanto solicitados por el navegador como soportados por tu sitio web. Esto produce una lista de todos los idiomas compatibles entre tu sitio y tu visitante. El valor es [] si ninguno de los idiomas solicitados por el navegador se encuentra en tu array de locales. Si el navegador no especifica ningún idioma preferido, entonces este valor será i18n.locales.
Astro.currentLocale: El locale calculado a partir de la URL actual, usando la sintaxis especificada en tu configuración de locales. Si la URL no contiene un prefijo /[locale]/, entonces el valor predeterminado será i18n.defaultLocale.

Para coincidir exitosamente con las preferencias de tus visitantes, proporciona tus codes usando el mismo patrón usado por el navegador.

Contribuir Comunidad Patrocinar