Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

i18n(zh-cn): Update internationalization.mdx #8383

Merged
merged 3 commits into from
May 24, 2024
Merged

i18n(zh-cn): Update internationalization.mdx #8383

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5cbcf3d
i18n(zh-cn): Update `internationalization.mdx`
huyikai May 24, 2024
aa01326
Update src/content/docs/zh-cn/guides/internationalization.mdx
huyikai May 24, 2024
cf267ce
Merge branch 'main' into 20240524-internationalization.mdx
liruifengv May 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 50 additions & 54 deletions src/content/docs/zh-cn/guides/internationalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,6 @@ export default defineConfig({

你可以通过[设置 `redirectToDefaultLocale: false`](/zh-cn/reference/configuration-reference/#i18nroutingredirecttodefaultlocale) 来选择退出此行为。这允许你拥有一个存在于你配置的语言环境文件夹结构之外的站点首页。


### `manual`

<p><Since v="4.6.0" /></p>
Expand Down Expand Up @@ -245,48 +244,48 @@ export const onRequest = sequence(
)
```

## 自定义语言环境路径
## `domains`

除了将你的网站支持的 `locales` 定义为字符串（例如 "en", "pt-br"）之外，Astro 还允许你将任意数量的[浏览器识别的语言 `codes`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax)映射到自定义的 URL `path` 上。虽然语言环境可以是任何格式的字符串，只要它们与你的项目文件夹结构相对应，但 `codes` 必须遵循浏览器接受的语法。
<p><Since v="4.9.0" /></p>

向 `locales` 数组传递一个对象，并使用 `path` 键来定义自定义的 URL 前缀，使用 `codes` 来指示映射到此 URL 的语言。在这种情况下，你的 `/[locale]/` 文件夹名称必须与 `path` 的值完全匹配，而你的 URL 将使用 `path` 的值来生成。
这个路由选项允许你为使用 [`@astrojs/node`](/zh-cn/guides/integrations-guide/node/) 或 [`@astrojs/vercel`](/zh-cn/guides/integrations-guide/vercel/) 适配器并配置了 `site` 的服务端渲染项目，按语言自定义你的域名。

如果你支持一个语言的多个变体（例如 `"fr"`、`"fr-BR"` 和 `"fr-CA"`），并且你希望所有这些变体都映射到同一个 URL `/fr/` 下，或者甚至完全自定义它（例如 `/french/`），这将非常有用：
添加 `i18n.domains` 来将你支持的任何 `locales` 映射到自定义 url：

```js title="astro.config.mjs" del={5} ins={6-9}
```js title="astro.config.mjs" {3-7} ins={14-21}
import { defineConfig } from "astro/config"
export default defineConfig({
site: "https://example.com",
output: "server", // 必须，没有预渲染的页面
adapter: node({
mode: 'standalone',
}),
i18n: {
defaultLocale: "en",
locales: ["es", "en", "fr"],
locales: ["es", "en", {
path: "french", // 不包含斜杠
codes: ["fr", "fr-BR", "fr-CA"]
}],
locales: ["es", "en", "fr", "ja"],
routing: {
prefixDefaultLocale: true
prefixDefaultLocale: false
},
domains: {
fr: "https://fr.example.com",
es: "https://example.es"
}
}
})
```

当使用来自 [`astro:i18n` 虚拟模块](/zh-cn/reference/api-reference/#国际化astroi18n) 的函数根据你的配置计算有效的 URL 路径时（例如 `getRelativeLocaleUrl()`），[请使用 `path` 作为 `locale` 的值](/zh-cn/reference/api-reference/#getlocalebypath)。

## 浏览器语言检测

Astro 的 i18n 路由允许你在按需渲染的页面中访问两个用于浏览器语言检测的属性：`Astro.preferredLocale` 和 `Astro.preferredLocaleList`。所有页面，包括静态预渲染页面，都可以访问 `Astro.currentLocale`。

这些属性结合了浏览器的 `Accept-Language` 头部信息和你的 `locales`（字符串或 `codes`），以自动遵循访问者的首选语言。

- [`Astro.preferredLocale`](/zh-cn/reference/api-reference/#astropreferredlocale): 如果访客的浏览器首选语言环境包含在你的 `locales` 数组中，Astro 可以为你的访客计算一个**首选语言环境**。如果没有这样的匹配存在，此值为 undefined。
所有未映射的 `locales` 将遵循你的 `prefixDefaultLocales` 配置。然而，即使这个值为 `false`，你的 `defaultLocale` 的页面文件也必须存在于一个本地化文件夹中。对于上面的配置，需要一个 `/en/` 文件夹。

- [`Astro.preferredLocaleList`](/zh-cn/reference/api-reference/#astropreferredlocalelist): 一个包含了浏览器请求并且你的网站支持的所有语言环境的数组。这将产生一个你的网站和访客之间所有兼容语言的列表。如果在你的 `locales` 数组中找不到浏览器请求的任何语言，该值为 `[]`。如果浏览器没有指定任何首选语言，则此值将是 [`i18n.locales`]。
根据上述配置：

- [`Astro.currentLocale`](/zh-cn/reference/api-reference/#astrocurrentlocale): 从当前 URL 计算的语言环境，使用你的 `locales` 配置指定的语法。如果 URL 不包含 `/[locale]/` 前缀，则该值将默认为 [`i18n.defaultLocale`](/zh-cn/reference/configuration-reference/#i18ndefaultlocale)。
- 文件 `/fr/about.astro` 将创建 URL `https://fr.example.com/about`。
- 文件 `/es/about.astro` 将创建 URL `https://example.es/about`。
- 文件 `/ja/about.astro` 将创建 URL `https://example.com/ja/about`。
- 文件 `/en/about.astro` 将创建 URL `https://example.com/about`。

为了成功匹配访客的偏好，请使用与[浏览器使用的模式](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax)相同的模式提供你的 `codes`。
上述 URL 也将通过 `getAbsoluteLocaleUrl()` 和 `getAbsoluteLocaleUrlList()` 函数返回。

## 回退策略
## `fallback`

Astro 的 i18n 路由允许你配置一个**回退路由策略**。当一个页面在某种语言下不存在时（例如，一个尚未翻译的页面），你可以基于每种语言将用户从一个语言环境重定向到另一个语言环境，而不是显示 404 页面。这在你还没有为每个路由准备好页面，但仍想为访客提供一些内容时非常有用。

Expand All @@ -307,49 +306,32 @@ export default defineConfig({

Astro 会确保 `src/pages/es/` 中的每个页面都在 `src/pages/fr` 中构建一个对应页面。如果页面尚未存在，那么将创建一个页面，并将其重定向到相应的 `es` 路由。

## `domains`（实验性功能）
## 自定义语言环境路径

<p><Since v="4.3.0" /></p>
除了将你的网站支持的 `locales` 定义为字符串（例如 "en", "pt-br"）之外，Astro 还允许你将任意数量的[浏览器识别的语言 `codes`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax)映射到自定义的 URL `path` 上。虽然语言环境可以是任何格式的字符串，只要它们与你的项目文件夹结构相对应，但 `codes` 必须遵循浏览器接受的语法。

这个路由选项允许你为使用 [`@astrojs/node`](/zh-cn/guides/integrations-guide/node/) 或 [`@astrojs/vercel`](/zh-cn/guides/integrations-guide/vercel/) 适配器并配置了 `site` 的服务端渲染项目，按语言自定义你的域名。
向 `locales` 数组传递一个对象，并使用 `path` 键来定义自定义的 URL 前缀，使用 `codes` 来指示映射到此 URL 的语言。在这种情况下，你的 `/[locale]/` 文件夹名称必须与 `path` 的值完全匹配，而你的 URL 将使用 `path` 的值来生成。

要在你的项目中启用这个功能，如果你还没有这样做的话，请根据你的偏好[配置 i18n 路由](#配置-i18n-路由)。然后，将 `experimental.i18nDomains` 标志设置为 `true` 并添加 `i18n.domains`，将你支持的任何 `locales` 映射到自定义 URL 上：
如果你支持一个语言的多个变体（例如 `"fr"`、`"fr-BR"` 和 `"fr-CA"`），并且你希望所有这些变体都映射到同一个 URL `/fr/` 下，或者甚至完全自定义它（例如 `/french/`），这将非常有用：

```js title="astro.config.mjs" {3-7} ins={14-21}
```js title="astro.config.mjs" del={5} ins={6-9}
import { defineConfig } from "astro/config"
export default defineConfig({
site: "https://example.com",
output: "server", // 必须，没有预渲染的页面
adapter: node({
mode: 'standalone',
}),
i18n: {
defaultLocale: "en",
locales: ["es", "en", "fr", "ja"],
locales: ["es", "en", "fr"],
locales: ["es", "en", {
path: "french", // 不包含斜杠
codes: ["fr", "fr-BR", "fr-CA"]
}],
routing: {
prefixDefaultLocale: false
},
domains: {
fr: "https://fr.example.com",
es: "https://example.es"
prefixDefaultLocale: true
}
},
experimental: {
i18nDomains: true
}
})
```

所有未映射的 `locales` 将遵循你的 `prefixDefaultLocales` 配置。然而，即使这个值为 `false`，你的 `defaultLocale` 的页面文件也必须存在于一个本地化文件夹中。对于上面的配置，需要一个 `/en/` 文件夹。

根据上述配置：

- 文件 `/fr/about.astro` 将创建 URL `https://fr.example.com/about`。
- 文件 `/es/about.astro` 将创建 URL `https://example.es/about`。
- 文件 `/ja/about.astro` 将创建 URL `https://example.com/ja/about`。
- 文件 `/en/about.astro` 将创建 URL `https://example.com/about`。

上述 URL 也将通过 `getAbsoluteLocaleUrl()` 和 `getAbsoluteLocaleUrlList()` 函数返回。
当使用来自 [`astro:i18n` 虚拟模块](/zh-cn/reference/api-reference/#国际化astroi18n) 的函数根据你的配置计算有效的 URL 路径时（例如 `getRelativeLocaleUrl()`），[请使用 `path` 作为 `locale` 的值](/zh-cn/reference/api-reference/#getlocalebypath)。

#### 限制

Expand All @@ -365,5 +347,19 @@ Astro 依赖以下头信息以支持此功能：

请确保你的服务器代理/托管平台能够提供这些信息。获取这些头信息失败将导致一个 404（状态码）页面。

## 浏览器语言检测

Astro 的 i18n 路由允许你在按需渲染的页面中访问两个用于浏览器语言检测的属性：`Astro.preferredLocale` 和 `Astro.preferredLocaleList`。所有页面，包括静态预渲染页面，都可以访问 `Astro.currentLocale`。

这些属性结合了浏览器的 `Accept-Language` 头部信息和你的 `locales`（字符串或 `codes`），以自动遵循访问者的首选语言。

- [`Astro.preferredLocale`](/zh-cn/reference/api-reference/#astropreferredlocale): 如果访客的浏览器首选语言环境包含在你的 `locales` 数组中，Astro 可以为你的访客计算一个**首选语言环境**。如果没有这样的匹配存在，此值为 undefined。

- [`Astro.preferredLocaleList`](/zh-cn/reference/api-reference/#astropreferredlocalelist): 一个包含了浏览器请求并且你的网站支持的所有语言环境的数组。这将产生一个你的网站和访客之间所有兼容语言的列表。如果在你的 `locales` 数组中找不到浏览器请求的任何语言，该值为 `[]`。如果浏览器没有指定任何首选语言，则此值将是 [`i18n.locales`]。

- [`Astro.currentLocale`](/zh-cn/reference/api-reference/#astrocurrentlocale): 从当前 URL 计算的语言环境，使用你的 `locales` 配置指定的语法。如果 URL 不包含 `/[locale]/` 前缀，则该值将默认为 [`i18n.defaultLocale`](/zh-cn/reference/configuration-reference/#i18ndefaultlocale)。

为了成功匹配访客的偏好，请使用与[浏览器使用的模式](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax)相同的模式提供你的 `codes`。

[`site`]: /zh-cn/reference/configuration-reference/#site
[`i18n.locales`]: /zh-cn/reference/configuration-reference/#i18nlocales
Loading