From 3a43de2620a0ec79f1f76b4f65b9ccf3e12e9b09 Mon Sep 17 00:00:00 2001 From: Paul Valladares <85648028+dreyfus92@users.noreply.github.com> Date: Wed, 17 Apr 2024 12:48:28 -0600 Subject: [PATCH] i18n(es): update `api-reference` (#7919) * i18n(es): update `api-reference` * Apply suggestions from code review * Apply suggestions from Waxer's review Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> * fix: missing translation --------- Co-authored-by: Waxer59 <78129249+Waxer59@users.noreply.github.com> Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../docs/es/reference/api-reference.mdx | 266 ++++++++++++++++++ 1 file changed, 266 insertions(+) diff --git a/src/content/docs/es/reference/api-reference.mdx b/src/content/docs/es/reference/api-reference.mdx index 05630efb193fe..ea63874e2ca87 100644 --- a/src/content/docs/es/reference/api-reference.mdx +++ b/src/content/docs/es/reference/api-reference.mdx @@ -1358,6 +1358,272 @@ Esta función puede ser utilizada por integraciones/adaptadores para ejecutar pr Una API de bajo nivel que toma cualquier valor y trata de devolver una versión serializada (un string) de él. Si el valor no se puede serializar, la función lanzará un error en tiempo de ejecución. +## Internacionalización (`astro:i18n`) + +

+ +Este módulo proporciona funciones para ayudarte a crear URLs utilizando los locales configurados en tu proyecto. + +Crear rutas para tu proyecto con el enrutador i18n dependerá de ciertos valores de configuración que hayas establecido y 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`](/es/reference/configuration-reference/#base) +- [`trailingSlash`](/es/reference/configuration-reference/#trailingslash) +- [`build.format`](/es/reference/configuration-reference/#buildformat) +- [`site`](/es/reference/configuration-reference/#site) + +También, ten en cuenta que las URLs devueltas por estas funciones para tu `defaultLocale` reflejarán tu configuración de `i18n.routing`. + +Para obtener características y ejemplos de uso, [consulta nuestra guía de enrutamiento i18n](/es/guides/internationalization/). + +### `getRelativeLocaleUrl()` + +`getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string` + +Usa esta función para obtener una ruta relativa para un idioma. Si el idioma no existe, Astro lanzará un error. + +```astro +--- +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()` + +`getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string` + +Usa esta función para obtener una ruta absoluta para un idioma cuando [`site`] tiene un valor. Si [`site`] no está configurado, la función devolverá una URL relativa. Si el idioma no existe, Astro lanzará un error. + + +```astro title="src/pages/index.astro" +--- +// Si `site` está configurado como `https://example.com` +getAbsoluteLocaleUrl("fr"); +// devuelve https://example.com/fr +getAbsoluteLocaleUrl("fr", ""); +// devuelve https://example.com/fr +getAbsoluteLocaleUrl("fr", "getting-started"); +// devuelve https://example.com/fr/getting-started +getAbsoluteLocaleUrl("fr_CA", "getting-started", { + prependWith: "blog" +}); +// devuelve 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 +--- +``` + +### `getRelativeLocaleUrlList()` + +`getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` + +Usa esto como [`getRelativeLocaleUrl`](#getrelativelocaleurl) para devolver una lista de rutas relativas para todos los idiomas. + + +### `getAbsoluteLocaleUrlList()` + +`getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]` + +Usa esto como [`getAbsoluteLocaleUrl`](/es/guides/internationalization/#custom-locale-paths) para devolver una lista de rutas absolutas para todos los idiomas. + +### `getPathByLocale()` + +`getPathByLocale(locale: string): string` + +Una función que devuelve el `path` asociado a uno o más `codes` cuando se configuran [rutas de idioma personalizadas](/es/guides/internationalization/#custom-locale-paths). + +```js title="astro.config.mjs" +export default defineConfig({ + i18n: { + locales: ["es", "en", { + path: "french", + codes: ["fr", "fr-BR", "fr-CA"] + }] + } +}) +``` + +```astro title="src/pages/index.astro" +--- +getPathByLocale("fr"); // devuelve "french" +getPathByLocale("fr-CA"); // devuelve "french" +--- +``` + +### `getLocaleByPath` + + `getLocaleByPath(path: string): string` + +Una función que devuelve el `code` asociado a un `path` de idioma. + +```js title="astro.config.mjs" +export default defineConfig({ + i18n: { + locales: ["es", "en", { + path: "french", + codes: ["fr", "fr-BR", "fr-CA"] + }] + } +}) +``` + +```astro title="src/pages/index.astro" +--- +getLocaleByPath("french"); // devuelve "fr" porque es el primer código configurado +--- +``` + +### `redirectToDefaultLocale()` + +`redirectToDefaultLocale(context: APIContext, statusCode?: ValidRedirectStatus): Promise` + +

+ +:::note +Disponible solo cuando `i18n.routing` está configurado 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. + +```js title="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()` + +`redirectToFallback(context: APIContext, response: Response): Promise` + +

+ +:::note +Disponible solo cuando `i18n.routing` está configurado en `"manual"` +::: + +Una función que te permite usar tu configuración de [`i18n.fallback`](/es/reference/configuration-reference/#i18nfallback) en tu propio middleware. + +```js title="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()` + +`notFound(context: APIContext, response: Response): Promise` + +

+ +:::note +Disponible solo cuando `i18n.routing` está configurado en `"manual"` +::: + +Usa esta función en tu middleware de enrutamiento para devolver un 404 cuando: +- la ruta actual no es una raíz. por ejemplo, `/` o `/` +- la URL no contiene un idioma configurado + +Cuando se pasa una `Response`, la nueva `Response` emitida por esta función contendrá los mismos encabezados de la respuesta original. + +```js title="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()` + +`middleware(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean })` + +

+ +:::note +Disponible solo cuando `i18n.routing` está configurado en `"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 solo agregar algunas excepciones a tu sitio web. + +```js title="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 que proviene del middleware de Astro i18n. + + return response; +}); + +export const onRequest = sequence(customLogic, middleware({ + prefixDefaultLocale: true, + redirectToDefaultLocale: false +})) +``` + +### `requestHasLocale()` + +`requestHasLocale(context: APIContext): boolean` + +

+ +:::note +Disponible solo cuando `i18n.routing` está configurado en `"manual"` +::: + +Verifica si la URL actual contiene un idioma configurado. Internamente, esta función usará `APIContext#url.pathname`. + +```js title="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 }); +}) +``` ## Componentes incorporados