#国际化

在 Rspress 中实现文档的国际化，需要完成以下步骤：

1. 在 rspress.config.ts 中配置语言列表和默认语言。
2. 新建各语言的文档和导航配置文件。

如果自定义组件需要翻译文本，或需要修改内置界面文案，可以继续阅读下方的可选章节。

#配置 rspress.config.ts

编辑 rspress.config.ts，配置以下选项：

• locales：站点支持的语言，以及各语言的标题、描述等站点信息。
• lang：站点的默认语言，其值应与 locales 中某一项的 lang 一致。

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

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

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

在文档根目录下，为每种语言创建一个目录。目录名应与 locales 中的 lang 值一致：

不同语言的文档分别存放在 docs 下的 en 和 zh 目录中。

在各语言目录中，通过 _nav.json 和 _meta.json 分别配置导航栏和侧边栏，具体可以参考自动化导航栏/侧边栏。

#导航栏 _nav.json

在各语言的 _nav.json 中，将 "text" 设为对应语言的文本：

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

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

#侧边栏 _meta.json

同样，在侧边栏配置中，将 "label" 设为对应语言的文本：

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

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

这些按语言编写的导航配置不需要单独定义翻译数据。

#定义翻译文本（可选）

完成上述配置后，多语言文档站点即可使用。如果自定义组件需要翻译文本，可以定义 welcomeMessage 等 key，并为各语言提供对应的文本。

Rspress 支持通过两种方式提供相同的翻译数据。

{
  "welcomeMessage": {
    "en": "Welcome",
    "zh": "欢迎"
  }
}

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

export default defineConfig({
  i18nSource: {
    welcomeMessage: {
      en: 'Welcome',
      zh: '欢迎',
    },
  },
});

如果同时配置，对象形式的 i18nSource 会覆盖 i18n.json 中相同 key、相同语言的文本，其他翻译仍会保留。

i18nSource 的函数用法请参考 API 文档。如果需要从其他位置读取 JSON 文件，可以配置 i18nSourcePath。

#自定义组件中使用 useI18n（可选）

在 MDX 组件或自定义主题中，可以通过 useI18n 获取上文定义的翻译文本。无论使用 i18n.json 还是 i18nSource，hook 的用法都相同：

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

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

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

更多用法和类型提示请参考 useI18n。

#修改 i18n 文案

Rspress 默认主题内置了多种语言的界面文案。缺少对应语言的翻译时，会回退到英文。

上文的翻译配置也可以用来覆盖内置文案，只需使用已有的 key。例如，在你选择的翻译来源中添加 editLinkText，修改编辑链接的文案：

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

export default defineConfig({
  i18nSource: {
    editLinkText: {
      en: 'Edit this page on GitLab',
      zh: '在 GitLab 上编辑此页',
    },
  },
});

如果使用 i18n.json，则在该文件中添加相同的条目：

{
  "editLinkText": {
    "en": "Edit this page on GitLab",
    "zh": "在 GitLab 上编辑此页"
  }
}

要补充其他语言，在 i18nSource 或 i18n.json 的各个文案 key 下添加对应的语言代码和翻译文本即可，语言代码应与站点配置一致。尚未翻译的内置文案会继续回退到英文。

修改界面文案是可选的，也适用于单语言站点。完整的内置文案 key 列表请参考 API 文档。