YARDのことの続きを書きたいと思いつつもなかなか辿りつきません。今回はPython製のドキュメントツールSphinxの話です。groongaのケースを例にしてSphinxで複数言語用のドキュメントを生成する方法の概要を紹介します。書いていたら長くなったので、具体的にどうするかというのは次の機会にします。

5/29にgroonga 1.2.2がリリースされました。今後は日本だけではなく世界でも使ってもらえるように、英語でも情報を発信していく方向になりました。そこで、今回のリリースに合わせてサイトデザインをリニューアルし、英語のページも用意しました。ただし、すでにあった日本語のコンテンツを今回のリリースで全部英語にした、というものではありません。今回のリリースでやったのは「日本語と英語という複数の言語で情報を発信する仕組み」を作るところまでです。せっかくなので、今回のリリースで導入した、Sphinxを使って実現している複数言語用のドキュメントを用意する仕組み（の概要）を紹介します。

なお、実際のページは以下のようになります。英語のページでも日本語の文章がまだまだ多く残っていますが、これはおいおい改善していく予定です¹。

• groongaのドキュメントページ（日本語）
• groongaのドキュメントページ（英語）

それぞれのページのヘッダーには他の言語へのリンクを用意してあり、すぐに対応する他の言語のページに行けるようになっています。

概要

まず、複数言語用のドキュメントを用意する仕組みの概要を説明します。

しばらくしたらリリースされるだろうSphinx 1.1には国際化機能がついています。（Sphinx本家の国際化についてのドキュメント（英語）。）今回紹介する仕組みはこの機能をベースにした仕組みになります²。

国際化機能を使うと、ベースとなるドキュメント1つから、そのドキュメントを他の言語に翻訳したドキュメントを複数生成することができます。ふつうはベースとなるドキュメントは英語で記述するので、以下のようなイメージになります。

ポイントは、本文のテキストだけ他の言語に翻訳すればよいというところです。章分けや説明する順序などの文章の構造などはベースとなる英語のドキュメントと同じものを共有します。

以下のようにドキュメント全体を翻訳する方法もありますが、この場合は文章の構造は共有していません。それぞれの翻訳されたドキュメントは翻訳した時点の英語のドキュメントの文書の構造をコピーしています。そのため、英語のドキュメントの文書の構造が変わったら、それにあわせて翻訳したドキュメントの方も変える必要があります³。

ドキュメント全体を翻訳する場合は元のドキュメントをコピーして翻訳するだけなので、通常のドキュメント作成作業と作業の流れはそれほど違いはないでしょう。

しかし、Sphinxが採用しているのは本文のみ翻訳する方法なので、通常の作業の流れとはだいぶ異なる流れになります。

翻訳の流れ

Sphinxでは「元の本文」を「翻訳した本文」に置き換えるためにGettextを使っています。gettextは昔からある国際化用ライブラリで、Sphinxが使っているのはgettextのPython実装です。

昔からあるだけあって、周辺ツールがそろっていることが利点です。例えば、元の本文と翻訳した本文とを比較して、変更された本文を自動検出するツールがあったりします。「一度翻訳して終わり」という場合は必要のないツールですが、「元の本文に追従して翻訳も更新する」という場合には有用なツールです。

groongaは継続して開発しているソフトウェアなのでドキュメントも更新されます。この場合は翻訳作業は以下のような流れになります。

「(1)本文を抽出」⁴と「(4)本文の差分抽出」⁵の部分がツールを使って自動化できる部分です。この部分は手動でやるには大変な部分なのでとても助かります。

「(3)更新」の部分は翻訳とは関係なく通常のドキュメント更新作業と同じです。

残りの(2)と(5)の「日本語へ翻訳」がメインの翻訳作業になりますが、ここの作業が通常の翻訳作業とやり方が違う部分になります。これは、gettextの作法に従う必要があるためです。

翻訳のしかた

gettextはPO (Portable Object)というファイルで「元のテキスト」と「翻訳したテキスト」を関連付けます。POは以下のようなフォーマットのテキストです⁶。

#: ${元のテキストがあるファイルのパス1}:${行1}
msgid "${元のテキスト1}"
msgstr "${翻訳したテキスト1}"

#: ${元のテキストがあるファイルのパス2}:${行2}
msgid "${元のテキスト2}"
msgstr "${翻訳したテキスト2}"

元の文書から本文を抽出した段階では${翻訳したテキスト}の部分が空になっているので、淡々とそこを埋めていく作業が翻訳作業になります。POファイルはテキストなので好きなエディタで編集できますが、専用の編集ツールもあります。Emacsのpo-modeやGNOMEのGtranslator、KDEのLokalizeなどです。

翻訳ができたら、それと元のドキュメントを使ってHTML形式でドキュメントを生成できます。

まとめ

Sphinxを使った複数言語用のドキュメントを用意する仕組みの概要を紹介しました。具体的な設定などは次の機会に紹介する予定ですが、待ちきれない人はgroongaのリポジトリをのぞいてみてください。

図はblockdiagで作りましたが、便利ですね。

ツイートする

フォローする