Referencia de la API de Internacionalización

Añadido en: astro@3.5.0

Este módulo proporciona funciones para ayudarte a crear URLs usando los locales configurados de tu proyecto.

Crear rutas para tu proyecto con el router i18n dependerá de ciertos valores de configuración que hayas establecido que afectan a las rutas de tus páginas. Al crear rutas con estas funciones, asegúrate de tener en cuenta tus ajustes 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 características y ejemplos de uso, consulta nuestra guía de enrutamiento i18n.

Importaciones desde astro:i18n

import {
  getRelativeLocaleUrl,
  getAbsoluteLocaleUrl,
  getRelativeLocaleUrlList,
  getAbsoluteLocaleUrlList,
  getPathByLocale,
  getLocaleByPath,
  redirectToDefaultLocale,
  redirectToFallback,
  notFound,
  middleware,
  requestHasLocale,
  normalizeTheLocale,
  pathHasLocale,
  toCodes,
  toPaths
 } from 'astro:i18n';

getRelativeLocaleUrl()

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

Usa esta función para recuperar una ruta relativa para un locale. Si el locale no existe, Astro lanza un error.

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

getRelativeLocaleUrl("fr");
// returns /fr

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

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

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

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

getAbsoluteLocaleUrl()

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

Usa esta función para recuperar una ruta absoluta para un locale cuando [site] tiene un valor. Si [site] no está configurado, la función devuelve una URL relativa. Si el locale no existe, Astro lanza un error.

src/pages/index.astro

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

// If `site` is set to be `https://example.com`

getAbsoluteLocaleUrl("fr");
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", "");
// returns https://example.com/fr/

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

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

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

getRelativeLocaleUrlList()

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

Usa esto como getRelativeLocaleUrl para devolver una lista de rutas relativas para todos los locales.

getAbsoluteLocaleUrlList()

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

Usa esto como getAbsoluteLocaleUrl para devolver una lista de rutas absolutas para todos los locales.

getPathByLocale()

Type: (locale: string) => string

Una función que devuelve la ruta asociada a uno o más códigos cuando se configuran rutas de locale 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"); // returns "french"
getPathByLocale("fr-CA"); // returns "french"
---

getLocaleByPath()

Type: (path: string) => string

Una función que devuelve el código asociado a una ruta de locale.

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"); // returns "fr" because that's the first code configured
---

redirectToDefaultLocale()

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

Añadido en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está establecido en "manual"

Una función que devuelve una Response que redirige al defaultLocale configurado. 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()

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

Añadido en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está establecido en "manual"

Una función que te permite usar 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()

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

Añadido en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está establecido en "manual"

Usa 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 un locale

Cuando se pasa una Response, la nueva Response emitida por esta función contendrá los mismos headers 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()

Tipo: (options: { fallbackType: "redirect" | "rewrite", prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Añadido en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está establecido en "manual"

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

Esto es útil cuando aún quieres usar la lógica i18n por defecto, pero añadir 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();

  // Custom logic after resolving the response.
  // It's possible to catch the response coming from Astro i18n middleware.

  return response;
});

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

requestHasLocale()

Type: (context: APIContext) => boolean

Añadido en: astro@4.6.0

Nota

Disponible solo cuando i18n.routing está establecido en "manual"

Verifica si la URL actual contiene un locale configurado. Internamente, esta función usará 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 });
})

normalizeTheLocale()

Type: (locale: string) => string

Reemplaza los guiones bajos (_) con guiones (-) en el locale dado antes de devolver una versión en minúsculas.

src/pages/index.astro

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

normalizeTheLocale("it_VT") // returns `it-vt`
// Assuming the current locale is `"pt-PT"`:
normalizeTheLocale(Astro.currentLocale) // returns `pt-pt`
---

pathHasLocale()

Type: (path: string) => boolean

Añadido en: astro@4.6.0

Verifica si la ruta dada contiene un locale configurado.

Esto es útil para prevenir errores antes de usar una utilidad i18n que depende de un locale de una ruta de URL.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

src/pages/index.astro

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

pathHasLocale("italiano"); // returns `true`
pathHasLocale("es"); // returns `true`
pathHasLocale('/es/blog/'); // returns `true`
pathHasLocale("it-VT"); // returns `false`
---

toCodes()

Type: (locales: Locales) => string[]

Añadido en: astro@4.0.0

Recupera los códigos de locale configurados para cada locale definido en tu configuración. Cuando múltiples códigos están asociados a un locale, solo el primero se añadirá al array.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

src/pages/index.astro

---
import { i18n } from "astro:config/client";
import { toCodes } from "astro:i18n";

toCodes(i18n!.locales); // ["it-VT", "es"]
---

toPaths()

Type: (locales: Locales) => string[]

Añadido en: astro@4.0.0

Recupera las rutas de locale configuradas para cada locale definido en tu configuración.

astro.config.mjs

export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})

src/pages/index.astro

---
import { i18n } from "astro:config/client";
import { toPaths } from "astro:i18n";

toPaths(i18n!.locales); // ["italiano", "es"]
---