Referencia de la API de Internacionalización

Agregado en: astro@3.5.0

Este módulo proporciona funciones para ayudarte a crear URLs utilizando las configuraciones regionales de tu proyecto.

La creación de rutas para tu proyecto con el enrutador i18n dependerá de ciertos valores de configuración que hayas establecido que afectan las rutas de tu página. Al crear rutas con estas funciones, asegúrate de tener en cuenta tus configuraciones individuales para:

• base
• trailingSlash
• build.format
• site

Además, ten en cuenta que las URLs devueltas creadas por estas funciones para tu defaultLocale reflejarán tu configuración de i18n.routing.

Para obtener ejemplos de características y uso, consulta nuestra guía de enrutamiento i18n.

Importaciones de astro:i18n

Sección titulada Importaciones de astro:i18n

import {
  getRelativeLocaleUrl,
  getAbsoluteLocaleUrl,
  getRelativeLocaleUrlList,
  getAbsoluteLocaleUrlList,
  getPathByLocale,
  getLocaleByPath,
  redirectToDefaultLocale,
  redirectToFallback,
  notFound,
  middleware,
  requestHasLocale,
} from "astro:i18n";

getRelativeLocaleUrl()

Sección titulada getRelativeLocaleUrl()

Tipo: (locale: string, path?: string, options?: GetLocaleOptions) => string

Utiliza esta función para recuperar una ruta relativa para una configuración regional. Si la configuración regional no existe, Astro arroja un error.

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

getRelativeLocaleUrl("fr");
// devuelve /fr

getRelativeLocaleUrl("fr", "");
// devuelve /fr/

getRelativeLocaleUrl("fr", "getting-started");
// devuelve /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
});
// devuelve /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false,
});
// devuelve /blog/fr_CA/getting-started
---

getAbsoluteLocaleUrl()

Sección titulada getAbsoluteLocaleUrl()

Tipo: (locale: string, path?: string, options?: GetLocaleOptions) => string

Utiliza esta función para recuperar una ruta absoluta para una configuración regional cuando [site] tiene un valor. Si [site] no está configurado, la función devuelve una URL relativa. Si la configuración regional no existe, Astro arroja un error.

src/pages/index.astro

---
import { getAbsoluteLocaleUrl } from "astro:i18n";

// Si `site` está configurado como `https://example.com`

getAbsoluteLocaleUrl("fr");
// devuelve [https://example.com/fr](https://example.com/fr)

getAbsoluteLocaleUrl("fr", "");
// devuelve [https://example.com/fr/](https://example.com/fr/)

getAbsoluteLocaleUrl("fr", "getting-started");
// devuelve [https://example.com/fr/getting-started](https://example.com/fr/getting-started)

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
});
// devuelve [https://example.com/blog/fr-ca/getting-started](https://example.com/blog/fr-ca/getting-started)

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false,
});
// devuelve [https://example.com/blog/fr_CA/getting-started](https://example.com/blog/fr_CA/getting-started)
---

getRelativeLocaleUrlList()

Sección titulada getRelativeLocaleUrlList()

Tipo: (path?: string, options?: GetLocaleOptions) => string[]

Utiliza esto como getRelativeLocaleUrl para devolver una lista de rutas relativas para todas las configuraciones regionales.

getAbsoluteLocaleUrlList()

Sección titulada getAbsoluteLocaleUrlList()

Tipo: (path?: string, options?: GetLocaleOptions) => string[]

Utiliza esto como getAbsoluteLocaleUrl para devolver una lista de rutas absolutas para todas las configuraciones regionales.

getPathByLocale()

Sección titulada getPathByLocale()

Tipo: (locale: string) => string

Una función que devuelve el path asociado a uno o más codes cuando se configuran rutas de configuración regional personalizadas.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: [
      "es",
      "en",
      {
        path: "french",
        codes: ["fr", "fr-BR", "fr-CA"],
      },
    ],
  },
});

src/pages/index.astro

---
import { getPathByLocale } from "astro:i18n";

getPathByLocale("fr"); // devuelve "french"
getPathByLocale("fr-CA"); // devuelve "french"
---

getLocaleByPath()

Sección titulada getLocaleByPath()

Tipo: (path: string) => string

Una función que devuelve el code asociado a un path de configuración regional.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: [
      "es",
      "en",
      {
        path: "french",
        codes: ["fr", "fr-BR", "fr-CA"],
      },
    ],
  },
});

src/pages/index.astro

---
import { getLocaleByPath } from "astro:i18n";

getLocaleByPath("french"); // devuelve "fr" porque ese es el primer código configurado
---

redirectToDefaultLocale()

Sección titulada redirectToDefaultLocale()

Tipo: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

Agregado en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está configurado como "manual"

Una función que devuelve una Response que redirige a la defaultLocale configurada. Acepta un código de estado de redirección válido opcional.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  if (context.url.pathname.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(context, 302);
  }
});

redirectToFallback()

Sección titulada redirectToFallback()

Tipo: (context: APIContext, response: Response) => Promise<Response>

Agregado en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está configurado como "manual"

Una función que te permite utilizar tu configuración de i18n.fallback en tu propio middleware.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();
  if (response.status >= 300) {
    return redirectToFallback(context, response);
  }
  return response;
});

notFound()

Sección titulada notFound()

Tipo: (context: APIContext, response?: Response) => Promise<Response> | undefined

Agregado en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está configurado como "manual"

Utiliza esta función en tu middleware de enrutamiento para devolver un 404 cuando:

• la ruta actual no es una raíz. ej. / o /<base>
• la URL no contiene una configuración regional

Cuando se pasa una Response, la nueva Response emitida por esta función contendrá los mismos encabezados de la respuesta original.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  const pathNotFound = notFound(context);
  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
});

middleware()

Sección titulada middleware()

Tipo: (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Agregado en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está configurado como "manual"

Una función que te permite crear programáticamente el middleware de Astro i18n.

Esto es útil cuando aún deseas utilizar la lógica i18n predeterminada, pero agregar solo algunas excepciones a tu sitio web.

middleware.js

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // Lógica personalizada después de resolver la respuesta.
  // Es posible capturar la respuesta proveniente del middleware Astro i18n.

  return response;
});

export const onRequest = sequence(
  customLogic,
  middleware({
    prefixDefaultLocale: true,
    redirectToDefaultLocale: false,
  }),
);

requestHasLocale()

Sección titulada requestHasLocale()

Tipo: (context: APIContext) => boolean

Agregado en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está configurado como "manual"

Verifica si la URL actual contiene una configuración regional configurada. Internamente, esta función utilizará APIContext#url.pathname.

middleware.js

import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  if (requestHasLocale(context)) {
    return next();
  }
  return new Response("Not found", { status: 404 });
});