Read the Docs で MkDocs のドキュメントを多言語対応させる方法
自作のライブラリで Read the Docs に配置したドキュメントを日本語対応させたのですが、
MkDocsの多言語対応に関する情報がネット上に少なく少し苦労したので、手順をまとめておきます。
1. 対象言語のドキュメントを用意する
まずは、対象言語用のドキュメントを用意します。
自作ライブラリでは docs ディレクトリ配下に ja ディレクトリを作成し、その中に日本語用ドキュメントを配置しました。
project/
├── docs/
│ ├── index.md # 英語版
│ └── ja/
│ └── index.md # 日本語版
└── mkdocs.yml
2. 対象言語用の mkdocs.yml を作成する
次に、対象言語用のMkDocs設定ファイルを作成します。
今回はmkdocs.ja.ymlという名称でプロジェクトルートに配置しました。
project/
├── docs/
│ ├── index.md # 英語版
│ └── ja/
│ └── index.md # 日本語版
├── mkdocs.yml # 英語版設定
└── mkdocs.ja.yml # 日本語版設定（新規作成）新しく作成した設定ファイルでは、既存のmkdocs.ymlの設定に加えて以下を追加します:
docs_dir: 対象言語のドキュメントが配置されているディレクトリを指定theme.language: 対象言語を指定extra.alternate: 言語切り替えのリンクを設定
docs_dir: docs/ja
theme:
name: material
language: ja
extra:
alternate:
- name: Japanese
link: /ja/
lang: ja
- name: English
link: /
lang: en
元の mkdocs.yml の更新
元のmkdocs.ymlにもextra.alternateを追加し、exclude_docsで対象言語用ディレクトリを除外します。
extra:
alternate:
- name: English
link: /
lang: en
- name: Japanese
link: /ja/
lang: ja
exclude_docs: |
ja/
3. 対象言語用の .readthedocs.yaml を作成する
次に、対象言語用の Read the Docs 設定ファイル .readthedocs.yaml を作成します。
設定ファイル名が固定のため、今回はdocs/jaディレクトリ内に配置しました。
project/
├── docs/
│ ├── index.md # 英語版
│ └── ja/
│ ├── index.md # 日本語版
│ └── .readthedocs.yaml # 日本語用Read the Docs設定（新規作成）
├── mkdocs.yml # 英語版設定
├── mkdocs.ja.yml # 日本語版設定
└── .readthedocs.yaml # 英語版Read the Docs設定-
.readthedocs.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(日本語用の設定ファイル)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. Read the Docs上で言語別プロジェクトを作成する
Read the Docsでは、各言語に専用のプロジェクトが必要です(公式ドキュメント参照)。
今回はeasybenchというプロジェクトの日本語版としてeasybench-jaプロジェクトを作成しました。
そして、新しく作成したプロジェクトの設定画面で以下調整を行います:
-
「言語」を対象言語に設定
-
.readthedocs.yamlのパスを以下のように設定する
5. 対象言語用プロジェクトを元プロジェクトの「翻訳」に設定する
最後に、作成した対象言語のプロジェクトを元プロジェクトの「翻訳」に設定します。
以下手順で行います:
- Read the Docsのメインプロジェクト（
easybench）の設定画面を開く - Hosting > 翻訳 セクションに移動
- 対象言語のプロジェクト（
easybench-ja）を追加
結果確認
設定完了後にドキュメントを更新すると、以下のように言語切り替えが行えるようになり、
多言語対応できました。
URLも以下のようなシンプルな形でアクセスできます。