MkDocs + plugin : mkdocs-static-i18n で多言語対応サイトを構築する

1. はじめに

• 過去に「この投稿」でMkDocsで多言語対応したwebサイトの作り方を検討したが、あまりにダサい作り方でした。
• さらに調査したところ、mkdocsのプラグイン「mkdocs-static-i18n」が使えそうだったので、その試使用した内容をまとめたいと思います。

2. 参考ページ

• mkdocs-static-i18n
  • 今回使い方を学習したプラグイン。あまり日本語で検討資料がないので手探りなところがあります。
• mkdocs-static-i18nのgitプロジェクト
  • ページの作り方を、実際のmkdocs-static-i18nのwebページを参考に検討しました。
• MKDocs – 拡張プラグイン集(1)
  • 本記事の内容とは直接リンクしないですが、MkDocsのpluginやextensionの参考にしました。

3. 動作確認した環境

• その１：Docker image python:3.9.7-slim
  • ※ここに必要なものをpip installして環境構築しました。ホストPCはUbuntu 20.04 + docker 20.10.5です。
  • pip install mkdocs mkdocs-material pygments plantuml_markdown mkdocs-static-i18n
  • mkdocs-material : 7.3以上
    • これは、サンプルページでnavigation.indexesオプションを使用しているためです。mkdocs-static-i18nは、7.1以上がよいです。
• その２：Github Pages
  • 本記事でリンクするサンプルページをデプロイしました。ただし、Github PagesやGithub Actionsの説明は、本記事の対象外とします。
  • 本記事で作成したサンプルページは、以下のGithubにコード、Pageを公開しています。
    • Gitリポジトリ : https://github.com/tomoten-umino/my-mkdocs-i18n-sample
    • Github Pages : https://tomoten-umino.github.io/my-mkdocs-i18n-sample/

4. mkdocs-static-i18nについて

※　https://ultrabug.github.io/mkdocs-static-i18n/topic2/より引用

• mkdocsのdocs以下に対応した言語向けのmdファイルを用意し、buildしたときにsite以下に各言語ごとのページを作成してくれます。mkdocs-static-i18nのサイトでは、英語とフランス語の2種類で説明しています。
  • 英語向けページは、○○.en.●●、フランス語向けページは○○.fr.●●でファイルを用意しています。

5. サンプルページ(英語＋日本語)

5.1. ディレクトリ・ファイル構造

my-mkdocs-i18n-sample/
├── LICENSE
├── README.md
├── docs
│   ├── index.ja.md
│   ├── index.md
│   └── topic1
│       ├── images
│       │   ├── DevelopmentAndDeployment.en.png
│       │   ├── DevelopmentAndDeployment.ja.png
│       │   ├── DirectoryStructure.en.png
│       │   ├── DirectoryStructure.ja.png
│       │   ├── MoveConfigDirectory.en.png
│       │   └── MoveConfigDirectory.ja.png
│       ├── index.en.md
│       ├── index.ja.md
│       ├── page1.en.md
│       └── page1.ja.md
├── mkdocs.yml
└── site

• サンプルページに書くネタがなかったので、過去に作成したportable-glusterのREADMEをpage1に載せています。imagesはそのページで参照しているものです。
• mkdocs-static-i18nの構成を参考に、必要なページのenファイルとjaファイルを用意しています。
• mkdocs buildした成果物はsite以下に格納されます。（これはデフォルト通り）

5.2. mkdocs.ymlの構成

site_name: Sample Document
theme:
  name: material
  features:
    - navigation.indexes
    - navigation.expand

nav:
  - Introduction:
    - index.md
  - MkDocs Sample:
    - topic1/index.en.md
    - topic1/page1.en.md

plugins:
  - search:
  - i18n:
      default_language: en
      languages:
        en: English
        ja: 日本語
      nav_translations:
        ja:
          site_name: サンプルドキュメント
          Introduction: はじめに
          MkDocs Sample: MkDocsのサンプル

markdown_extensions:
    - codehilite:
        noclasses: true
        pygments_style: colorful
        linenums: true
    - plantuml_markdown:
        server: http://www.plantuml.com/plantuml
    - admonition
    - pymdownx.superfences
    - pymdownx.details

• themeではmaterialデザインを使用しています。2022/10/17現在、7.3.3を適用しています。
  • navigation.indexesのオプションが便利です。navのタグのところにindexページを割り当てることができます。
  • 上記例では、「MkDocs Sample」のところにtopic1/index.en.mdの内容を表示できます。（通常設定では、そもそも「MkDocs Sample」のページを開けません）
• navを記載するときは、pluginsのi18nでdefault指定した言語のファイルで記載しました。（今の所意図通りに動いています）
• nav_translationsを用いると、navのタグ名称を各言語に応じて置換することができます。
• その他のextensionは好みです。「MKDocs – 拡張プラグイン集(1)」を参考にしております。

5.3. ビルド

FROM python:3.9.7-slim

RUN apt-get update && \
    apt-get install -y apt-utils && \
    apt-get install -y make git vim fontconfig  && \
    pip install --upgrade pip && \
    pip install mkdocs mkdocs-material pygments plantuml_markdown mkdocs-static-i18n

CMD ["/bin/sh"]

• ローカルでビルドする場合は、上記で示したDockerfileでコンテナイメージを作成して、その中でビルドできます。

$ docker build -f (Dockerfileパス)/Dockerfile -t mkdocks-test:test .
（docker buildビルドされる）
# コードをクローン
$ git clone https://github.com/tomoten-umino/my-mkdocs-i18n-sample.git
# dockerコンテナ起動
$ docker container run -it --net=host -v `pwd`/my-mkdocs-i18n-sample:/root/my-mkdocs-i18n-sample mkdocs-test:test
# コンテナ内
$ cd /root/my-mkdocs-i18n-sample
$ mkdocs build --clean
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /root/my-mkdocs-i18n-sample/site
INFO     -  Building en documentation
INFO     -  Building ja documentation
INFO     -  Translating navigation to ja
INFO     -  Documentation built in 1.10 seconds
# 簡易サーバ起動
$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Adding 'ja' to the 'plugins.search.lang' option
INFO     -  Cleaning site directory
INFO     -  Building en documentation
INFO     -  Building ja documentation
INFO     -  Translating navigation to ja
INFO     -  Documentation built in 1.07 seconds
INFO     -  [12:47:18] Serving on http://127.0.0.1:8000/

• ホストPCのブラウザから、http://127.0.0.1:8000/ にアクセスすると、以下のようなページが表示されます。

5.4. サンプルページのデモ

• 実際のサンプルページは、Github Pagesの「https://tomoten-umino.github.io/my-mkdocs-i18n-sample/」に公開しています。
• 英語サイトと日本語サイトの切り替えは以下のような感じになります。

6. おわりに

• mkdocs-static-i18nを使った所感としては、相当使いやすいです。
  • 特に、nav_translationsが優秀で、言語を切り替えたときに左側のリスト表示も対応できるのがよいです。デフォルトを英語にしましたが、各言語ごとに設定できるのでデフォルトを日本語にしても有効です。
  • 唯一、site_nameが切り替えられていないです。これは割り切って英語にしました。
• 過去の「投稿」は完全に黒歴史です。記事は消さないですが。