#国际化

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

1. 定义 I18n 文本数据。
2. 配置语言列表，rspress.config.ts 中的 locales。
3. 配置默认语言，rspress.config.ts 中的 lang。
4. 新建不同的语言版本的文档。
5. 配置侧边栏和导航栏。
6. 自定义组件中使用 useI18n。

#定义 I18n 文本数据

在当前工作区新建 i18n.json，目录结构如下：

在这个 JSON 文件中，你可以定义国际化所需的文本，类型定义如下:

export interface I18n {
  // key 为文本 id
  [key: string]: {
    // key 为语言
    [key: string]: string;
  };
}

举个例子:

{
  "gettingStarted": {
    "en": "Getting Started",
    "zh": "开始"
  },
  "features": {
    "en": "Features",
    "zh": "特性"
  },
  "guide": {
    "en": "Guide",
    "zh": "指南"
  }
}

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

#配置 locales

rspress.config.ts 中的 locales，用于配置站点的语言、标题、描述等信息，主要围绕站点本身的信息来配置。

import { defineConfig } from '@rspress/core';

export default defineConfig({
  // locales 为一个对象数组
  locales: [
    {
      lang: 'en',
      // 导航栏切换语言的标签
      label: 'English',
      title: 'Rspress',
      description: 'Static Site Generator',
    },
    {
      lang: 'zh',
      label: '简体中文',
      title: 'Rspress',
      description: '静态网站生成器',
    },
  ],
});

对于其它的国际化主题参数配置，请参考 API 类型。

#配置 lang 默认语言

在配置完 locales 之后，你需要通过 lang 配置文档的默认语言，如下例子所示:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  lang: 'en',
});

这很重要，因为对于默认语言下的路由，Rspress 会去掉语言前缀，比如 /en/guide/getting-started 会被转换为 /guide/getting-started。

#新建不同的语言版本的文档

在做好上面的配置后，我们就可以开始新建不同语言版本的文档了，非常简单，我们只需要在文档根目录下新建如下的结构即可：

可以看到，我们把不同语言的文档放在了 docs 目录下的 en 和 zh 目录中，这样就可以方便地区分不同语言的文档了。

#配置 _nav.json 和 _meta.json

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

#导航栏 _nav.json

在导航栏配置中，你可以将 text 指定为 i18n key，比如:

[
  {
    "text": "guide",
    "link": "/guide/start/introduction"
  },
  {
    "text": "api",
    "link": "/api/"
  }
]

其中，text 为 guide，这个值会被自动翻译为 指南 或者 Guide，具体取决于 i18n.json 和当前语言。

#侧边栏 _meta.json

在侧边栏配置中，你可以将 label 指定为 i18n key，比如:

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

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

#自定义组件中使用 useI18n

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

Rspress 提供了 useI18n 这个 hook 来获取国际化文本，使用方式如下：

import { useI18n } from '@rspress/core/runtime';

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

  return <div>{t('gettingStarted')}</div>;
};

为了获得更好的类型提示，你可以在 tsconfig.json 中配置 paths:

{
  "compilerOptions": {
    "paths": {
      "i18n": ["./i18n.json"]
    }
  }
}

然后在组件中这样使用:

import { useI18n } from '@rspress/core/runtime';

const MyComponent = () => {
  const t = useI18n<typeof import('i18n')>();

  return <div>{t('gettingStarted')}</div>;
};

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