跳转到内容

国际化 API 参考

添加于: astro@3.5.0

此模块提供了一些函数,帮助你使用项目配置的语言环境设置创建 URL。

使用 i18n 路由为你的项目创建路由将依赖于你设置的某些配置值,这些值会影响你的页面路由。使用这些函数创建路由时,请确保考虑到你的个人设置,包括:

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

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

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

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

getRelativeLocaleUrl(locale: string, path?: string, options?: GetLocaleOptions): string

使用此函数来检索一个语言环境的相对路径。如果该语言环境不存在,Astro 会抛出一个错误。

---
getRelativeLocaleUrl("fr");
// 返回 /fr
getRelativeLocaleUrl("fr", "");
// 返回 /fr
getRelativeLocaleUrl("fr", "getting-started");
// 返回 /fr/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
// 返回 /blog/fr-ca/getting-started
getRelativeLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
// 返回 /blog/fr_CA/getting-started
---

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

当 [site] 配置了值时,使用这个函数来检索一个语言环境的绝对路径。如果 [site] 没有被配置,该函数将返回一个相对 URL。如果语言环境不存在,Astro 会抛出一个错误。

src/pages/index.astro
---
// 如果 `site` 被设置为 `https://example.com`
getAbsoluteLocaleUrl("fr");
// 返回 https://example.com/fr
getAbsoluteLocaleUrl("fr", "");
// 返回 https://example.com/fr
getAbsoluteLocaleUrl("fr", "getting-started");
// 返回 https://example.com/fr/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog"
});
// 返回 https://example.com/blog/fr-ca/getting-started
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
prependWith: "blog",
normalizeLocale: false
});
// 返回 https://example.com/blog/fr_CA/getting-started
---

getRelativeLocaleUrlList()

段落标题 getRelativeLocaleUrlList()

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

像使用 getAbsoluteLocaleUrl 那样使用此函数,返回所有语言环境的绝对路径列表。

getAbsoluteLocaleUrlList()

段落标题 getAbsoluteLocaleUrlList()

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

像使用 getAbsoluteLocaleUrl 那样使用此函数,返回所有语言环境的绝对路径列表。

类型:(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"); // 返回 "french"
getPathByLocale("fr-CA"); // 返回 "french"
---

类型:(path: string) => string

此函数返回与语言环境 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"); // 返回 "fr",因为这是首个配置的代码
---

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

添加于: astro@4.6.0

此函数返回一个 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);
}
})

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

添加于: astro@4.6.0

此函数允许你在自己的中间件中使用你的 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;
})

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

添加于: astro@4.6.0

当以下情况发生时,在你的路由中间件中使用此函数来返回一个 404 错误:

  • 当前路径不是根路径。例如://<base>
  • URL 中不包含语言环境代码

当传递了一个 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();
})

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

添加于: astro@4.6.0

此函数允许你以编程方式创建 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();
// 在这里解析响应后的自定义逻辑。
// 可以捕获来自 Astro i18n 中间件的响应。
return response;
});
export const onRequest = sequence(customLogic, middleware({
prefixDefaultLocale: true,
redirectToDefaultLocale: false
}))

类型:(context: APIContext) => boolean

添加于: astro@4.6.0

检查当前 URL 是否包含已配置的语言环境代码。在内部,此函数将使用 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 });
})
贡献

你有什么想法?

社区
京ICP备15031610号-99