#i18n

To internationalize a Rspress documentation site, complete the following steps:

1. Configure the language list and default language in rspress.config.ts.
2. Create docs and navigation files for each language.

If your custom components need translated text, or you want to change the built-in UI text, see the optional sections below.

#Configure rspress.config.ts

Edit rspress.config.ts to configure:

• locales: The supported languages and site-level information for each language, such as title and description.
• lang: The default site language. Its value should match a lang entry in locales.

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

export default defineConfig({
  lang: 'en',
  locales: [
    {
      lang: 'en',
      // The label in the navbar language switcher
      label: 'English',
      title: 'Rspress',
      description: 'Static Site Generator',
    },
    {
      lang: 'zh',
      label: '简体中文',
      title: 'Rspress',
      description: '静态网站生成器',
    },
  ],
});

#Create docs for each language

Create a directory for each language under your docs root. The directory names should match the lang values in locales:

Here, docs for different languages live in the en and zh directories under docs, making each language version easy to distinguish.

Within each language directory, use _nav.json and _meta.json to configure the navbar and sidebar. For details, see Autogenerated navigation.

#Navigation bar _nav.json

In each language's _nav.json, set "text" to the text for that language:

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

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

#Sidebar _meta.json

Similarly, set "label" to the text for each language:

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

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

These language-specific navigation files do not require separate translation data.

#Define translations (optional)

The setup above is enough for a multilingual documentation site. If your custom components need translated text, define a key such as welcomeMessage and provide a value for each language.

Rspress accepts the same translation data in two ways.

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

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

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

If you configure both, the object form of i18nSource takes precedence for the same key and language; other translations are preserved.

For the function form of i18nSource, see the API reference. To load the JSON file from another location, use i18nSourcePath.

#Use useI18n in custom components (optional)

In MDX components or a custom theme, use useI18n to read the translations defined above. The hook works the same whether you use i18n.json or i18nSource:

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

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

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

For more usage details and type hints, see useI18n.

#Customize i18n text

Rspress's default theme includes UI translations for several languages. Missing translations fall back to English.

The translation sources described above can also override built-in text: use an existing key instead of defining a new one. For example, add editLinkText to your chosen source to customize the edit link text:

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

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

If you use i18n.json, add the same entry there instead:

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

To add another language, add its language code and translated text under each text key in i18nSource or i18n.json, using the same language code as your site configuration. Any built-in text you have not translated will continue to use its English fallback.

Customizing UI text is optional and also works on single-language sites. For the complete list of built-in translation keys, see the API reference.