To achieve document internationalization in Rspress, you need to do the following:
locales
and themeConfig.locales
。useI18n
in custom components.Create a new i18n.json
in the current workspace, the directory structure is as follows:
In this JSON file, you can define the text needed for internationalization, the type definition is as follows:
For example:
These text data are used in both config file and custom components, which will be introduced in detail later.
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.In the default theme, themeConfig.locales
also contains all the fields in locales
, the former takes precedence.
For other international theme parameters, please refer to API type.
After configure locales
data, you need configure the default language of the document via lang
, as shown in the following example:
This is important because for routes in the default language, the framework will remove the language prefix, such as /zh/guide/getting-started
will be converted to /guide/getting-started
.
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:
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.
Through the _meta.json file, we can configure the content of the nav bar and sidebar. For details, please refer to Auto Nav/Sidebar.
In the _meta.json configuration at the navigation bar level, you can specify text
as an i18n key, for example:
Here, text
is guide
, this value will be automatically translated into 指南
or Guide
, depending on the current language.
In the _meta.json configuration at the sidebar level, you can specify label
as an i18n key, for example:
Here, label
is getting-started
, this value will be automatically translated into 开始
or Getting Started
, depending on the current language.
useI18n
in custom componentsIn 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:
For better type hinting, you can configure paths
in tsconfig.json:
Then use it like this in the component:
This way you get type hints for all literal keys defined in i18n.json
.