Internationalization#

To achieve document internationalization in Rspress, you need to do the following:

1. Defines I18n text data.
2. Configure locales and themeConfig.locales。
3. Configure the default language.
4. Create documents in different language version.
5. Configure sidebar and navbar.
6. Use useI18n in custom components.

Defines I18n text data#

Create a new i18n.json in the current workspace, the directory structure is as follows:

1.
2├── docs
3├── i18n.json
4├── package.json
5├── tsconfig.json
6└── rspress.config.ts

In this JSON file, you can define the text needed for internationalization, the type definition is as follows:

export interface I18n {
  // key: text id
  [key: string]: {
    // key: language
    [key: string]: string;
  };
}

For example:

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

These text data are used in both config file and custom components, which will be introduced in detail later.

Configure locales#

In rspress.config.ts, you can configure locales data in two places:

• locales, used to configure the lang, title, description and other information of the site, mainly around the information of the site itself.
• themeConfig.locales, used to configure the theme's lang, outline title, previous page/next page text and other information, mainly for theme-related config.

import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en',
      // The label in nav bar to switch language
      label: 'English',
      title: 'Rspress',
      description: 'Static Site Generator',
    },
    {
      lang: 'zh',
      label: '简体中文',
      title: 'Rspress',
      description: '静态网站生成器',
    },
  ],
  themeConfig: {
    locales: [
      {
        lang: 'en',
        outlineTitle: 'ON THIS Page',
      },
      {
        lang: 'zh',
        outlineTitle: '大纲',
      },
    ],
  },
});

For other international theme parameters, please refer to API type.

Configure the default language#

After configure locales data, you need configure the default language of the document via lang, as shown in the following example:

import { defineConfig } from 'rspress/config';

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

This is important because for routes in the default language, the framework will remove the language prefix, such as /en/guide/getting-started will be converted to /guide/getting-started.

Create documents in different language#

After the above configuration, we can start to create documents in different language versions. It is very simple. We only need to create the following structure in the document root directory:

docs
├── en
│   ├── api
│   │   └── index.md
│   └── guide
│       └── getting-started.md
│       └── features.md
└── zh
    ├── api
    │   └── index.md
    └── guide
        └── getting-started.md
        └── features.md

As you can see, we put documents in different languages ​​in the en and zh directories under the docs directory, so that we can easily distinguish documents in different languages.

Configuring _meta.json#

Through the _meta.json file, we can configure the content of the nav bar and sidebar. For details, please refer to Auto Nav/Sidebar.

Navigation Bar Level#

In the _meta.json configuration at the navigation bar level, you can specify text as an i18n key, for example:

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

Here, text is guide, this value will be automatically translated into 指南 or Guide, depending on the current language.

Sidebar Level#

In the _meta.json configuration at the sidebar level, you can specify label as an i18n key, for example:

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

Here, label is gettingStarted, this value will be automatically translated into 开始 or Getting Started, depending on the current language.

Use useI18n in custom components#

In the process of MDX development or custom theme development, you may write some custom components, which also need to use international text, so how to get it?

The framework provides useI18n this hook to get the internationalized text, the usage is as follows:

import { useI18n } from 'rspress/runtime';

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

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

For better type hinting, you can configure paths in tsconfig.json:

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

Then use it like this in the component:

import { useI18n } from 'rspress/runtime';

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

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

This way you get type hints for all literal keys defined in i18n.json.