国际化
在 Rspress 中实现文档的国际化,你需要做如下的操作:
- 定义 I18n 文本数据。
- 配置
locales
和 themeConfig.locales
。
- 配置默认语言。
- 新建不同的语言版本的文档。
- 配置侧边栏和导航栏。
- 自定义组件中使用
useI18n
。
定义 I18n 文本数据
在当前工作区新建 i18n.json
,目录结构如下:
1.
2├── docs
3├── i18n.json
4├── package.json
5├── tsconfig.json
6└── rspress.config.ts
在这个 JSON 文件中,你可以定义国际化所需的文本,类型定义如下:
export interface I18n {
// key 为文本 id
[key: string]: {
// key 为语言
[key: string]: string;
};
}
举个例子:
i18n.json
{
"getting-started": {
"zh": "开始",
"en": "Getting Started"
},
"features": {
"zh": "基础功能",
"en": "Features"
},
"guide": {
"zh": "指南",
"en": "Guide"
}
}
这些文本数据在配置文件和自定义组件中都会用到,后文会详细介绍。
配置 locales
数据
在 rspress.config.ts
中,你可以通过两个地方来配置 locales
数据:
locales
,用于配置站点的语言
、标题
、描述
等信息,主要围绕站点本身的信息来配置。
themeConfig.locales
,用于配置主题的语言
、大纲栏标题
、上一页/下一页文本
等信息,主要进行主题相关的配置。
rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
// locales 为一个对象数组
locales: [
{
lang: 'en',
// 导航栏切换语言的标签
label: 'English',
title: 'Modern.js',
description: 'Modern.js 文档框架',
},
{
lang: 'zh',
// 导航栏切换语言的标签
label: '简体中文',
title: 'Modern.js',
description: 'Rspress',
},
],
themeConfig: {
locales: [
{
lang: 'en',
outlineTitle: 'ON THIS Page',
},
{
lang: 'zh',
outlineTitle: '大纲',
},
],
},
});
注意
默认主题中, themeConfig.locales
也包含 locales
中的所有字段,前者优先级更高。
对于其它的国际化主题参数配置,请参考 API 类型。
配置默认语言
在配置完 locales
之后,你需要通过 lang
配置文档的默认语言,如下例子所示:
rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
lang: 'zh',
});
这很重要,因为对于默认语言下的路由,框架会去掉语言前缀,比如 /zh/guide/getting-started
会被转换为 /guide/getting-started
。
新建不同的语言版本的文档
在做好上面的配置后,我们就可以开始新建不同语言版本的文档了,非常简单,我们只需要在文档根目录下新建如下的结构即可:
docs
├── en
│ ├── api
│ │ └── index.md
│ └── guide
│ └── getting-started.md
│ └── features.md
└── zh
├── api
│ └── index.md
└── guide
└── getting-started.md
└── features.md
可以看到,我们把不同语言的文档放在了 docs
目录下的 en
和 zh
目录中,这样就可以方便地区分不同语言的文档了。
配置 _meta.json
通过 _meta.json 文件,我们可以配置导航栏和侧边栏的内容,具体可以参考自动化导航栏/侧边栏。
导航栏级别
在导航栏级别的 _meta.json 配置中,你可以将 text
指定为 i18n key,比如:
_meta.json
[
{
"text": "guide",
"link": "/guide/start/getting-started",
"activeMatch": "/guide/"
}
]
其中,text
为 guide
,这个值会被自动翻译为 指南
或者 Guide
,具体取决于当前语言。
侧边栏级别
在侧边栏级别的 _meta.json 配置中,你可以将 label
指定为 i18n key,比如:
_meta.json
[
{
"type": "dir",
"name": "start",
"label": "getting-started"
}
]
其中,label
为 getting-started
,这个值会被自动翻译为 开始
或者 Getting Started
,具体取决于当前语言。
自定义组件中使用 useI18n
在 MDX 开发或者自定义主题开发的过程中,你可能会写一些自定义组件,这些组件中也需要使用到国际化文本,那么如何获取呢?
框架提供了 useI18n
这个 hook 来获取国际化文本,使用方式如下:
import { useI18n } from 'rspress/runtime';
const MyComponent = () => {
const t = useI18n();
return <div>{t('getting-started')}</div>;
};
为了获得更好的类型提示,你可以在 tsconfig.json 中配置 paths
:
{
"compilerOptions": {
"paths": {
"i18n": ["./i18n.json"]
}
}
}
然后在组件中这样使用:
import { useI18n } from 'rspress/runtime';
const MyComponent = () => {
const t = useI18n<typeof import('i18n')>();
return <div>{t('getting-started')}</div>;
};
这样你就可以获得 i18n.json
中定义的所有文本 key 的类型提示了。