概要
Sphinxはドキュメント作成ツールです。ドキュメントの生成はreStructuredTextというマークアップ言語を用いてその構造などを指定することによって行います。$\mathrm{\LaTeX}$のようにマークアップによってドキュメントの体裁などを細かく制御したりかっこいい数式を記述したりすることができます。結果はHTMLやPDF形式などの形式で得ることができます（PDF出力は要$\mathrm{\LaTeX}$）。さらに，作成したドキュメントはReadTheDocsというホスティングサービスを用いて無償で簡単に公開することも可能となっています。本稿では，なるべく手間をかけずにSphinxで作成したドキュメントを国際化する方法を考えたいと思います。
Sphinxに限りませんが，ドキュメントを国際化する場合単にテキストを（機械）翻訳すれば終了とは行かないと思います。見出しがあったり強調表示があったり相互参照があったりと本文テキスト以外の様々な要素があり，これらは不変にしながらテキスト部分のみを翻訳したデータを用意する必要があるためです。ここでは以下のような方法による国際化を紹介したいと思います。
- "Portable Object Template (pot)"と"Portable Object (po)"ファイルを生成する
- polibライブラリーを用いて国際化対象の文字列を抽出し，結果を機械翻訳にかけることによって目的の言語に変換する
- Sphinxを走らせてHTMLなりPDFなりを生成する
Portable Object TemplateおよびPortable Objectファイルの生成
Sphinxにおいては標準的な国際化方法
が用意されています。手続きとしては，まず以下のコマンドによってpotファイルを生成します。
make gettext
このコマンドは通常のmake htmlやmake latexpdfなどを行うディレクトリーと同じディレクトリーにおいて実行します。するとbuild/gettextディレクトリーにターゲットのSphinxプロジェクトにある*.rstファイルと同じ数の*.potファイルが生成されているはずです。その内容は，典型的には以下のようになります。
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2026, jkoga
# This file is distributed under the same license as the xxx package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
../../source/aa.rst:2714
msgid "元の言語"
msgstr ""
...
...
msgidに翻訳元の言語の文字列が入ります。msgstrには翻訳文が入ります。
*.potファイルはテンプレートファイルであり，これ自体に直接手を加えることは想定されていません。実際の翻訳結果はsphinx-intlを用いて得られる*.poファイルに書き込みます。以下，上述の標準的な国際化方法の説明にそって解説します。
sphinx-intlがインストールされていない場合以下の要領でインストールします。
pip install sphinx-intl
conf.pyファイル (Sphinxの設定用スクリプト；位置は通常sourceディレクトリー直下) に以下のような設定を書き込みます。
locale_dirs = ['locales/']
locale_dirsに指定するパスは任意ですが，この例のlocales/が推奨とされています。
次のようにsphinx-intlを実行します。
sphinx-intl update -p build/gettext -l en
Create: source/locales/en/LC_MESSAGES/index.po
Create: source/locales/en/LC_MESSAGES/sections.po
...
...
sphinx-intlに渡すパスは先のgettextコマンドの結果が出力されたディレクトリーです。-lオプションにターゲット言語を指定します。この例ではenすなわち英語を指定しています。結果は，先ほどconf.pyに指定したディレクトリーの下のLC_MESSAGESディレクトリーに出力されます。ここに出力された*.poファイルのmsgstrに翻訳を記述します。
翻訳
Sphinxは翻訳まではしてくれません。翻訳は，なんらかの方法で人間が用意します。ここではGoogle Cloud Translation APIを用いて翻訳する方法を紹介したいと思います。Google Cloud Translation APIは有償サービスですが，多くのケースで必要十分と思われる月50万文字までの無償枠があります（ただし請求先のひもづいたアカウントが必要です）50万文字は入力ベースで言語を問わないので，入力が日本語だと少し有利ですね。
Google Cloud Translation API
Google Cloud Translation APIはいくつかのバージョンがありますが，ここではバージョン3を用いて翻訳をします。使える状態にするにはいくつか設定を施す必要があります。ここでその解説をしてみたいと思います。
- Google Cloud Cosoleにログインし，「プロジェクト」を作成します
- 作成したプロジェクトを選んだ状態にし，左上の三本線をクリックし，「APIとサービス」⇒「ライブラリ」を選び，「Cloud Translation API」を選びます
- 結果得られる画面の「有効にする」ボタンをクリックします。この際課金アカウントの紐づけが必要です
- 左上の三本線をクリックし，「IAMと管理」⇒「サービスアカウント」を選び，「サービスアカウントを作成」をクリックします
- 結果得られた「サービスアカウント」を選択し，上部のタブから「権限」を選びます
- そこで「アクセスを管理する」⇒右の画面にでてくる「ロール」⇒下の方に現われる「ロールを管理」と選んでいきます
- フィルタに「Cloud Translation」と入力し，結果から「Cloud Translation API ユーザー」を選びます。すると必要な権限がすべて一括で設定されます
- 次に上部タブの「鍵」を選びます。「キーを追加」から「新しい鍵を作成」を選び，さらに「JSON」を選びます
- 鍵ファイルがダウンロードされるので，ローカルパソコンに保存します
ややこしいですが，以上で利用する準備が整います。
polib
sphinx-intlによって作成した*.poファイル内の翻訳対象をトラバースするためにpolibというライブラリーを用います。以下の要領でインストールしましょう。
pip install polib
変換用スクリプト
準備は整ったので，機械翻訳を適用するスクリプトを実行します。
まずは，先にダウンロードしたJSONの鍵ファイルへのパスを環境変数 GOOGLE_APPLICATION_CREDENTIALSに設定しておく必要があります。
export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_JSONFILE
スクリプトは以下のようなものになります。
import polib
from google.cloud import translate
# 認証情報の設定（環境変数 GOOGLE_APPLICATION_CREDENTIALS に JSON鍵ファイルのパスを指定しておく）
client = translate.TranslationServiceClient()
parent = "projects/exalted-pattern-xxxx-q0/locations/global"
SOURCE_LANG = "ja"
TARGET_LANG = "en"
# .potファイルの読み込み
pot = polib.pofile("aa.po")
for entry in pot:
if entry.msgid and not entry.msgstr:
response = client.translate_text(
request={
"parent": parent,
"contents": [entry.msgid],
"mime_type": "text/plain",
"source_language_code": SOURCE_LANG,
"target_language_code": TARGET_LANG,
}
)
translated = response.translations[0].translated_text
entry.msgstr = translated
# 翻訳結果を保存（.poファイルとして）
pot.save("aa.po")
parentにはプロジェクトのIDを入力する必要があります。ダウンロードしたJSONファイルの中身をみるとproject_idというエントリーがあります。ここで指定されている文字列をprojects/のあとに記述し，さらに/locations/globalと記述します。この点と*.poファイルの名前以外はそのまま使えるスクリプトになっているはずです。
この例ではこのスクリプトを実行するディレクトリーの下のaa.poファイルから翻訳元entry.msgidをAPIに流し，結果を翻訳先entry.msgstrに格納しています。結果は同じaa.poに保存しています。対象となる*.poファイルは適宜調整して利用してください。source以下のファイル構成が複雑ならos.walkなどを使うと効率よく翻訳できるかもしれません。
HTML, PDFの作成
以上の作業によってreStructuredTextに対する修正はできました。Sphinxを走らせて，目的の言語のドキュメントを作成しましょう。以下のようなコマンドを用います。
make -e SPHINXOPTS="-D language='en'" html
これで目的の言語のHTMLファイルが得られるはずです。元の言語でPDFが作成できる状態になっていればhtmlのかわりにlatexpdfとすればPDFを得ることができますが，用いる$\mathrm{\LaTeX}$のコンパイラーも目的の言語のそれに切り替わるため，うまくコンパイルできない場合がある点に注意が必要です。著者の経験では，日本語から英語に変換する場合数式環境でマルチバイト文字を使っているとビルドすることができませんでした。
結び
本稿ではSphinxを用いて作成したドキュメントを国際化する方法について解説しました。Sphinxが提供する機能を用いて*.potファイルを生成し，さらに*.poファイルを生成する方法を紹介しました。翻訳自体はGoogle Cloud Translation APIを用いてスクリプトで実施する方法を紹介しました。あとはSphinx実行時に適切なオプションを渡せば目的の言語のドキュメントを得ることができます。本稿の内容が皆さまの作業の一助になれば幸いです。