How to Make MkDocs Documentation Multilingual on Read the Docs

I added Japanese language support to the documentation of my library hosted on Read the Docs.
Since there wasn’t much information online about multilingual support for MkDocs, I had some difficulties, so I’m documenting the procedure here.

1. Prepare documents for the target language

First, prepare the documents for your target language.
In my library, I created a ja directory under the docs directory and placed the Japanese documentation there.

project/
├── docs/
│   ├── index.md          # English version
│   └── ja/
│       └── index.md      # Japanese version
└── mkdocs.yml

2. Create a mkdocs.yml for the target language

Next, create a MkDocs configuration file for the target language.
In this case, I created mkdocs.ja.yml in the project root.

project/
├── docs/
│   ├── index.md          # English version
│   └── ja/
│       └── index.md      # Japanese version
├── mkdocs.yml            # English config
└── mkdocs.ja.yml         # Japanese config (new)

For this new file, keep all the original settings from mkdocs.yml and add the following settings:

• docs_dir: Specify the directory where the target language documents are located
• theme.language: Specify the target language
• extra.alternate: Configure language switching links

docs_dir: docs/ja

theme:
  name: material
  language: ja

extra:
  alternate:
    - name: Japanese
      link: /ja/
      lang: ja
    - name: English
      link: /
      lang: en

Update the original mkdocs.yml

Add extra.alternate to the original mkdocs.yml as well, and exclude the target language directory using exclude_docs.

extra:
  alternate:
    - name: English
      link: /
      lang: en
    - name: Japanese
      link: /ja/
      lang: ja

exclude_docs: |
  ja/

3. Create a .readthedocs.yaml for the target language

Next, create a Read the Docs configuration file .readthedocs.yaml for the target language.
Since the filename is fixed, I placed it in the docs/ja directory.

project/
├── docs/
│   ├── index.md                    # English version
│   └── ja/
│       ├── index.md                # Japanese version
│       └── .readthedocs.yaml       # Japanese Read the Docs config (new)
├── mkdocs.yml                      # English config
├── mkdocs.ja.yml                   # Japanese config
└── .readthedocs.yaml               # English Read the Docs config

• .readthedocs.yaml (Default configuration file (project root))

  yaml

  version: 2
  
  build:
    os: ubuntu-24.04
    tools:
      python: "3.13"
  
  mkdocs:
    configuration: mkdocs.yml
  
  python:
    install:
      - method: pip
        path: .
        extra_requirements:
          - docs

• docs/ja/.readthedocs.yaml (Configuration file for Japanese)

  yaml

  version: 2
  
  build:
    os: ubuntu-24.04
    tools:
      python: "3.13"
  
  mkdocs:
    configuration: mkdocs.ja.yml
  
  python:
    install:
      - method: pip
        path: .
        extra_requirements:
          - docs

4. Create a language-specific project on Read the Docs

Read the Docs requires a dedicated project for each language (see official documentation).
In this case, I created a project called easybench-ja as a Japanese version of the easybench project.

Then, make the following adjustments in the settings page of the newly created project:

1. Set “Language” to your target language

2. Set the path to .readthedocs.yaml as shown below

   

5. Set the target language project as a “translation” of the original project

Finally, set the target language project as a “translation” of the original project.

Follow these steps:

1. Open the settings page of the main project on Read the Docs (easybench)
2. Navigate to Hosting > Translations section
3. Add the target language project (easybench-ja)

Checking the result

After completing the setup and updating the documentation, you can switch languages as shown below,
making the documentation multilingual.

The URLs are also simple and straightforward:

• Original URL: https://easybench.readthedocs.io/
• Japanese version URL: https://easybench.readthedocs.io/ja/