国际化

在 Rspress 中实现文档的国际化,你需要做如下的操作:

  1. 定义 I18n 文本数据。
  2. 配置 localesthemeConfig.locales
  3. 配置默认语言。
  4. 新建不同的语言版本的文档。
  5. 配置侧边栏和导航栏。
  6. 自定义组件中使用 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
{
  "gettingStarted": {
    "en": "Getting Started",
    "zh": "开始"
  },
  "features": {
    "en": "Features",
    "zh": "特性"
  },
  "guide": {
    "en": "Guide",
    "zh": "指南"
  }
}

这些文本数据在配置文件自定义组件中都会用到,后文会详细介绍。

配置 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 目录下的 enzh 目录中,这样就可以方便地区分不同语言的文档了。

配置 _meta.json

通过 _meta.json 文件,我们可以配置导航栏和侧边栏的内容,具体可以参考自动化导航栏/侧边栏

导航栏级别

在导航栏级别的 _meta.json 配置中,你可以将 text 指定为 i18n key,比如:

_meta.json
[
  {
    "text": "guide",
    "link": "/guide/start/getting-started",
    "activeMatch": "/guide/"
  }
]

其中,textguide,这个值会被自动翻译为 指南 或者 Guide,具体取决于当前语言。

侧边栏级别

在侧边栏级别的 _meta.json 配置中,你可以将 label 指定为 i18n key,比如:

_meta.json
[
  {
    "type": "dir",
    "name": "start",
    "label": "gettingStarted"
  }
]

其中,labelgettingStarted,这个值会被自动翻译为 开始 或者 Getting Started,具体取决于当前语言。

自定义组件中使用 useI18n

在 MDX 开发或者自定义主题开发的过程中,你可能会写一些自定义组件,这些组件中也需要使用到国际化文本,那么如何获取呢?

框架提供了 useI18n 这个 hook 来获取国际化文本,使用方式如下:

import { useI18n } from 'rspress/runtime';

const MyComponent = () => {
  const t = useI18n();

  return <div>{t('gettingStarted')}</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('gettingStarted')}</div>;
};

这样你就可以获得 i18n.json 中定义的所有文本 key 的类型提示了。