国际化 API 参考

新增于： astro@3.5.0

该模块提供了帮助你使用项目中已配置的地区（locales）来创建 URL 的函数。

使用 i18n 路由为你的项目创建路由将取决于你设置的某些影响页面路由的配置值。当使用这些函数创建路由时，请务必考虑你对以下内容的个别设置：

• base
• trailingSlash
• build.format
• site

此外，请注意，这些函数为你的 defaultLocale 创建的返回 URL 将反映你的 i18n.routing 配置。

有关功能和使用示例，请参阅我们的 i18n 路由指南。

从 astro:i18n 导入

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

getRelativeLocaleUrl()

类型： (locale: string, path?: string, options?: GetLocaleOptions) => string

使用此函数可以获取一个地区（locale）的相对路径。如果该地区不存在，Astro 会抛出一个错误。

---
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()

类型： (locale: string, path?: string, options?: GetLocaleOptions) => string

当 [site] 有值时，使用此函数可以获取一个地区（locale）的绝对路径。如果 [site] 没有配置，该函数将返回一个相对 URL。如果该地区不存在，Astro 会抛出一个错误。

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()

类型： (path?: string, options?: GetLocaleOptions) => string[]

像使用 getRelativeLocaleUrl 一样使用此函数，以返回所有地区（locales）的相对路径列表。

getAbsoluteLocaleUrlList()

类型： (path?: string, options?: GetLocaleOptions) => string[]

像使用 getAbsoluteLocaleUrl 一样使用此函数，以返回所有地区（locales）的绝对路径列表。

getPathByLocale()

类型： (locale: string) => string

当配置了自定义地区路径时，该函数会返回与一个或多个 codes 相关联的 path。

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()

类型： (path: string) => string

一个返回与地区（locale）path 相关联的 code 的函数。

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()

类型： (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

添加于： astro@4.6.0

注意

仅当 i18n.routing 设置为 "manual" 时可用

一个返回 Response 的函数，该响应会重定向到已配置的 defaultLocale。它接受一个可选的有效重定向状态码。

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()

类型： (context: APIContext, response: Response) => Promise<Response>

添加于： astro@4.6.0

注意

仅当 i18n.routing 设置为 "manual" 时可用

一个允许你在自己的中间件中使用 i18n.fallback 配置的函数。

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()

类型： (context: APIContext, response?: Response) => Promise<Response> | undefined

添加于： astro@4.6.0

注意

仅当 i18n.routing 设置为 "manual" 时可用

在你的路由中间件中使用此函数，以便在以下情况下返回 404：

• 当前路径不是根路径。例如 / 或 /<base>
• URL 不包含地区（locale）

当传递一个 Response 时，此函数发出的新 Response 将包含原始响应的相同标头。

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()

类型： (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

添加于： astro@4.6.0

注意

仅当 i18n.routing 设置为 "manual" 时可用

一个允许你以编程方式创建 Astro i18n 中间件的函数。

当你仍想使用默认的 i18n 逻辑，但只想为你的网站添加少数例外情况时，这个功能非常有用。

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
}))

requestHasLocale()

类型： (context: APIContext) => boolean

添加于： astro@4.6.0

注意

仅当 i18n.routing 设置为 "manual" 时可用

检查当前 URL 是否包含一个已配置的地区（locale）。在内部，此函数将使用 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 });
})