169 lines
4.5 KiB
Markdown
169 lines
4.5 KiB
Markdown
---
|
||
title: 国际化
|
||
icon: material-symbols-light:language
|
||
createTime: 2024/03/05 10:01:26
|
||
permalink: /guide/locales/
|
||
tags:
|
||
- 指南
|
||
- i18n
|
||
---
|
||
|
||
本指南将帮助您快速为 VuePress 主题配置多语言支持。通过简单的目录结构和配置调整，即可实现专业的国际化站点。
|
||
|
||
## 目录结构规划
|
||
|
||
首先创建符合多语言要求的目录结构。以下示例展示支持中文、英文和法文的项目布局：
|
||
|
||
::: file-tree
|
||
|
||
- docs
|
||
- **en** # 英文文档目录
|
||
- foo.md
|
||
- README.md # 英文首页
|
||
- **fr** # 法文文档目录
|
||
- foo.md
|
||
- README.md # 法文首页
|
||
- foo.md
|
||
- README.md # 中文首页
|
||
:::
|
||
|
||
**目录结构说明**：
|
||
|
||
- `docs/en/` - 存储英文版本文档
|
||
- `docs/fr/` - 存储法文版本文档
|
||
- `docs/` - 存储默认语言（中文）文档
|
||
|
||
::: important 保持文件结构一致性
|
||
在不同语言目录中，请保持相同的文件名和目录结构。这确保主题能够在语言切换时正确导航到对应语言的文档版本。
|
||
:::
|
||
|
||
## VuePress 基础配置
|
||
|
||
### 设置默认语言
|
||
|
||
在配置文件 `.vuepress/config.ts` 中声明默认语言：
|
||
|
||
```ts title=".vuepress/config.ts" twoslash
|
||
import { defineUserConfig } from 'vuepress'
|
||
|
||
export default defineUserConfig({
|
||
// 设置默认语言代码
|
||
lang: 'zh-CN', // [!code ++]
|
||
// 配置多语言支持
|
||
locales: {
|
||
'/': { lang: 'zh-CN', title: '博客' }, // 简体中文作为默认语言
|
||
}
|
||
})
|
||
```
|
||
|
||
### 添加其他语言支持
|
||
|
||
扩展 `locales` 配置来支持更多语言：
|
||
|
||
```ts title=".vuepress/config.ts" twoslash
|
||
import { defineUserConfig } from 'vuepress'
|
||
|
||
export default defineUserConfig({
|
||
lang: 'zh-CN',
|
||
locales: {
|
||
'/': { lang: 'zh-CN', title: '博客' }, // 简体中文
|
||
'/en/': { lang: 'en-US', title: 'Blog' }, // 美式英语 // [!code ++]
|
||
'/fr/': { lang: 'fr-FR', title: 'Le blog' }, // 法语 // [!code ++]
|
||
}
|
||
})
|
||
```
|
||
|
||
**配置要点**：
|
||
|
||
- `locales` 的键名（如 `/en/`）对应文档目录中的语言文件夹名称
|
||
- 这些键名同时作为各语言页面的访问路径前缀
|
||
- 每个语言必须设置正确的 `lang` 属性，即使只使用单一语言
|
||
|
||
::: tip 语言代码规范
|
||
|
||
- **路径键名**：遵循 [ISO 639](https://zh.wikipedia.org/wiki/ISO_639-1) 标准（如英语使用 `/en/`）
|
||
- **语言代码**：使用 [BCP47](https://www.ietf.org/rfc/bcp/bcp47.txt) 标准格式（如英语使用 `en-US`）
|
||
:::
|
||
|
||
## 主题多语言配置
|
||
|
||
在主题配置中通过 `locales` 字段为每种语言定制化界面元素：
|
||
|
||
```ts title=".vuepress/config.ts" twoslash
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
lang: 'zh-CN', // [!code focus:6]
|
||
locales: {
|
||
'/': { lang: 'zh-CN', title: '博客' },
|
||
'/en/': { lang: 'en-US', title: 'Blog' },
|
||
'/fr/': { lang: 'fr-FR', title: 'Le blog' },
|
||
},
|
||
theme: plumeTheme({
|
||
// 主题级多语言配置
|
||
locales: { // [!code focus:20]
|
||
// 简体中文配置
|
||
'/': {
|
||
selectLanguageName: '简体中文',
|
||
navbar: [
|
||
{ text: '首页', link: '/' },
|
||
{ text: '博客', link: '/blog/' },
|
||
]
|
||
},
|
||
// 英文配置
|
||
'/en/': {
|
||
selectLanguageName: 'English',
|
||
navbar: [
|
||
{ text: 'Home', link: '/en/' },
|
||
{ text: 'Blog', link: '/en/blog/' },
|
||
]
|
||
},
|
||
// 法文配置
|
||
'/fr/': { // [!code focus:7]
|
||
selectLanguageName: 'Français',
|
||
navbar: [
|
||
{ text: 'Accueil', link: '/fr/' },
|
||
{ text: 'Le Blog', link: '/fr/blog/' },
|
||
]
|
||
}
|
||
}
|
||
})
|
||
})
|
||
```
|
||
|
||
**关键配置项**：
|
||
|
||
- `selectLanguageName`：在语言选择器中显示的语言名称
|
||
- `navbar`：各语言独有的导航栏配置
|
||
- 所有主题配置项均支持在 `locales` 中按语言重写
|
||
|
||
## 配置一致性要求
|
||
|
||
确保 VuePress 配置与主题配置的路径键名完全匹配：
|
||
|
||
```ts
|
||
export default {
|
||
// VuePress 配置
|
||
locales: {
|
||
'/': { /* 中文配置 */ },
|
||
'/en/': { /* 英文配置 */ },
|
||
},
|
||
|
||
// 主题配置
|
||
theme: plumeTheme({
|
||
locales: {
|
||
'/': { /* 中文主题配置 */ },
|
||
'/en/': { /* 英文主题配置 */ }
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
## 扩展阅读
|
||
|
||
- [主题 Locales 配置](../../config/theme.md#locale-配置) - 了解各语言专属的主题行为配置
|
||
- [多语言文本配置](../../config/locales.md) - 掌握界面文本的国际化定制方法
|
||
|
||
通过以上配置，您的文档站点将具备完整的多语言支持能力，为用户提供更友好的国际化访问体验。
|