国际化

国际化

在 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

{
  "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 目录下的 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": "gettingStarted"
  }
]

其中，label 为 gettingStarted，这个值会被自动翻译为 开始 或者 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 的类型提示了。

国际化

国际化