ククログ

株式会社クリアコード > ククログ > Sphinxに言語切り替えリンクを付ける方法

Sphinxに言語切り替えリンクを付ける方法

ちゃんと書こうとするといつまでも完成しないような気がしたので、小出しにすることにしました1

groongaのリファレンスマニュアルは英語版と日本語版を用意しています。英語版ページには同じ内容の日本語版ページへのリンク、日本語版ページには同じ内容の英語版ページのリンクを用意しています。各ページの上のところにある国旗画像がそのリンクです。以下のように国旗画像で言語を表現しています。

他言語版のページへのリンク

これはSphinxのテーマを使って実現しています。そのやり方について説明します。

ディレクトリ構成

以下のようなディレクトリ構成になっているとします。en/html/以下にはsphinx -Dlanguage=en ...で生成したHTMLがあり、ja/html/以下にはsphinx -Dlanguage=ja ...で生成したHTMLがあります。

.
|-- en
|   `-- html
|       | ... HTMLがたくさん
|       `-- index.html
`-- ja
    `-- html
        | ... HTMLがたくさん
        `-- index.html

この場合、ja/html/index.htmlでは../../en/html/index.htmlへリンクを張ればよいことになります。

設定方法

conf.pyとテーマのlayout.htmlを設定します。

まず、conf.pyで以下のように設定し、-Dlanguage=...で指定した言語をテーマ内で参照できるようにします。

conf.py:

html_context = {"language": language}

次に、テーマ内でlanguageの値を参照してリンクを生成します。groongaのようにページの先頭の方にリンクを入れる場合は以下のようにします。

layout.html:

{% extends "default/layout.html" %}
{% block header %}
  <ul>
  {%- if language != "en" %}
    <li><a href="{{ pathto('../../en/html/', 1) }}{{ pathto(pagename, 0, '.') }}">English</a></li>
  {%- endif %}
  {%- if language != "ja" %}
    <li><a href="{{ pathto('../../ja/html/', 1) }}{{ pathto(pagename, 0, '.') }}">日本語</a></li>
  {%- endif %}
  </ul>
  {{ super() }}
{% endblock %}

pathto(pagename, 0, '.')でトップページから現在のパスへの相対パスを取得している所がポイントです。Sphinxのドキュメントにはこのやり方が書いていませんでしたが、Sphinxのソースを読んでみたらできそうだったのでこうしました。

languageを参照して出力内容を変えるという手法は他のものにも応用できそうですね。

まとめ

groongaのリファレンスマニュアルで実現している、他言語ページへのリンクを自動生成する方法を紹介しました。Sphinxで複数言語用のドキュメントを生成する場合に利用してみてください。

  1. まとまっていなくて、後から参照しづらいのではないかという点が心配です。