po4a+Zanataでpoetryのドキュメント翻訳

どうも横滑りのプロ @cocoatomo です. poetry のドキュメントを精読のために翻訳をしようとしたら, lunr-languages に PR を送っていました.

精読目的の翻訳

自分が技術文書を翻訳する目的の高い割合を占めるのが「精読」です. Python 公式ドキュメントPipenv のドキュメント の翻訳の目的はだいたい「精読」のためです.

Python における依存関係管理, パッケージング

正直に言うと, 今でも Python のパッケージングまわりのことをちゃんと分かっていません. setup.py 書くたびにあちこち調べて python setup.py install を何度も試して, なんとか書いているレベルです.

最近, Python の依存関係管理やパッケージングまわりが賑やかなようで, その文脈で poetry というツール名を聞くようになり, 勉強がてらドキュメントを翻訳することにしました.

ドキュメントジェネレーター

普段は Sphinx というドキュメントジェネレーターで生成されたドキュメントの翻訳をやっています. そのため, どのように .pot (Portable Object Template) ファイルや .po (Portable Object) ファイルを生成し, 翻訳を行った後にどのように .mo (Machine Object) ファイルに変換し, 原文を訳文に差し替えるのかについては理解しています.

しかし, poetry ドキュメントは MkDocs という初めて聞くツールで生成されていて, ソースファイルのフォーマットが Markdown という今まで扱ったことのないものばかりでした. (Sphinx のソースファイルは reStructuredText 形式です.)

ワークフロー

初めてのこととは言え, 翻訳プロジェクトを進めるにあたって大事な要点はだいたい把握しているので, 後は必要なツールを揃えるだけです.

その要点についてはこのスライドにほぼ全部書き出してあります.

Sphinx が支える翻訳ドキュメント

最終的な構成をまとめると次のようになります.

.pot ファイル生成:po4a
翻訳:Zanata
訳文適用:po4a
翻訳ドキュメントビルド:MkDocs
ドキュメント公開:GitHub Pages

原文抜き出し (.pot ファイル生成)

po4a の po4a-gettextize コマンドで .pot ファイルを生成します.

翻訳 (.po ファイル生成, 訳文記入)

Transifex というサービスに一番慣れてますが, せっかくなので Zanata という翻訳管理サービスを使ってみます.

訳文適用

po4a の po4a-translate コマンドで訳文を適用して .md ファイルを作成します.

翻訳ドキュメントビルド

訳文が適用された .md ファイルを使ってドキュメントをビルドします. 翻訳版のドキュメント用の設定ファイル mkdocs.ja.yml を指定してビルドコマンドを実行します.

poetry で使っているテーマはレポジトリに push されていなかったので, mkdocs-material というテーマを使いました.

ドキュメント公開

ドキュメントはテーマをそのまま使いたかったので, GitHub Pages で HTML/CSS/JavaScript 等々そのままアップロードしてます.

Makefile

一連のコマンドをオプションも含めて覚えるのが苦手なので Makefile を用意しています.

興味がある方はこちらを覗いてみてください.

https://github.com/cocoatomo/poetry/blob/5f5711c2df2f8080b6aa683dcc6967170642ea07/docs/Makefile

終わりに

あくまで自分の勉強や経験値UPのための趣味でやっている翻訳ですが

趣味でやっている翻訳が, 誰かの助けになっている

  ∧∧
  ( ・ω・)
 _| ⊃/(___
/ ヽ_(____/

俺はそういうことに幸せを感じるんだ

 <⌒/ヽ-、__
/<_/____/

そういうことです.