私はPython初心者で,Pythonの公式ドキュメントをマニュアルとしてよく見る。
公式オリジナルの英語版が https://docs.python.org/3/ で公開されていて,その日本語に翻訳されたものが https://docs.python.jp/3/ で公開されている。
PythonをインストールするとWindowsのヘルプファイルも提供されるが,日本語翻訳したものは公式にはリリースされていないみたい。
一応,Python Japanese Environmentで,Python 2.7の日本語Windowsヘルプファイルがあるのだが,なぜかエラーが毎回表示されてしまう。また,最新のバージョンのものは残念ながら見つからない。
そこで,日本語翻訳されたWindowsのヘルプファイルを作成してみることにした。
Pythonドキュメント日本語訳プロジェクトの活動のおかげで,日本語訳のリソースは手に入れることが出来る。
これを使用して,日本語のPythonのヘルプファイルを作成してみる。
まず,Pythonのドキュメントから日本語のドキュメント(HTML)を作成してみる。
ドキュメントを作成するのに必要なツールSphinx(Pythonで動作する)やTransifex(翻訳プロジェクト)などを,インストールする。
> pip install sphinx > pip install sphinx-intl > pip install blurb > pip install transifex-client
Pythonのドキュメントを作成するのに,Pythonのソースコードにドキュメントのソースも含まれているので必要になる。
Pythonの公式サイトから,Pythonのソースコード(ドキュメントも含んでいる)をダウンロードする。これには,日本語翻訳されたドキュメントのリソースを含んではいない。
適当な作業ディレクトリで解凍する。
> wget https://www.python.org/ftp/python/3.7.2/Python-3.7.2.tgz > tar xvfz Python-3.7.2.tgz > cd Python-3.7.2
別の方法として,Pythonドキュメント日本語訳プロジェクトから,Sphinxの設定が含まれたPythonのソースコードをダウンロード出来る。
ただ,翻訳作業が終了後にリポジトリが更新されるので,最新バージョンが用意されるまでは時間がかかる。いまのところ用意されている最新版は3.6.5だった。
> git clone https://github.com/python-doc-ja/cpython-doc-intl > cd cpython-doc-intl > git checkout intl-3.6
Sphinxを使用して日本語ドキュメントが出力されるように,conf.pyファイルのGeneral configurationのどこかに,以下の追加・修正をする。
language = 'ja' locale_dirs = ['locale/'] gettext_compact = False : : today_fmt = '%m/%d/%Y'
Pythonの公式サイトからのソースコードには日本語化したドキュメントが入っていない。Pythonドキュメントプロジェクト transifex で日本語の翻訳作業が行われているので,そこから日本語訳リソースをダウンロードする。
Pythonドキュメントプロジェクト transifex に参加して,翻訳作業を行うことが出来る。翻訳作業は大変な労力が必要なので多くの人の協力が必要。参加したいなぁ。
Pythonドキュメント日本語訳プロジェクトのリソースを使う場合は,transifexのアカウントを作成する必要はない。
まず,transifex でアカウントを作成する。アカウントが作成できたらAPIキーを作成しておく。翻訳者として登録しない場合は,アカウントを使用できるのは15日間。
~/.transifexrcファイルを以下の内容で作成する。
[https://www.transifex.com] hostname = https://www.transifex.com token = xxxxxxxxxxxxxx username = <ユーザー名> password = <パスワード>
tokenには,作成したAPIキーを設定する。
翻訳のチームに参加ボタンを押して参加を表明し,承認されれば(メールで送られてくる),翻訳リソースをダウンロードできるようになる。
Pythonドキュメントプロジェクト transifex での翻訳作業の成果を, Pythonドキュメント日本語訳プロジェクト に公開しているようだ。
翻訳するための設定ファイル.tx/configファイルを作成する。
> cd locale > sphinx-intl create-txconfig
Pythonドキュメントソースからメッセージカタログ(.pot)ファイルを作成する。
> cd .. > sphinx-build -b gettext . locale/pot
翻訳するための設定ファイル.tx/configファイルをpotファイル情報で更新する。
> cd locale > sphinx-intl update-txconfig-resources --pot-dir pot --transifex-project-name="python-newest" > awk '/file_filter/{sub("locales/","");print $0} !/file_filter/{print $0}' .tx/config > .tx/config.2 > cp .tx/config.2 .tx/config > rm .tx/config.2 > tx pull -l ja
とすると,現在翻訳作業中の翻訳リソースの.poファイルがダウンロードできる。
Pythonドキュメント日本語訳プロジェクトのリポジトリに日本語訳されたドキュメントリソースがある。最新はバージョン3.6.5。このバージョンで良ければ,以下のようにして.poファイルをダウンロードする。
> cd Doc > git clone https://github.com/python-doc-ja/py36-locale locale
.poファイルは,Doc/locale/ja/LC_MESSAGES/にダウンロードされる。
バージョン3.7.2の場合は,
> cd Doc > git clone https://github.com/python-doc-ja/py37-locale locale
とすれば良いと思われるが,残念ながらまだリポジトリにアップされていない。(翻訳作業自体は進んでいる。)
conf.pyファイルのOptions for HTML outputに,以下の修正をする。
html_last_updated_fmt = '%m/%d/%Y'
翻訳した.poファイル(実際には.moファイル)を使用して,ドキュメントファイル(HTMLファイル)をビルドしてみる。
> make clean html
自分で翻訳を修正したりしたい場合は,Doc/locale/ja/LC_MESSAGES/にある.poファイルを,好みに編集してビルドすれば良い。
これでうまく行けば,日本語訳されたHTMLのドキュメントがDoc/build/htmlに作成される。
HTMLのドキュメントが作成出来れば,Windowsで使われるヘルプファイルである.chmファイルを作成できる。
作成するには,Microsoftの HTML Help Workshop が必要になる。
DocディレクトリにMakefile等があるので,それを使ってHTML Help Workshopが使用するプロジェクトファイルを作成する。
> make htmlhelp
Doc\build\htmlhelpに,HTMLファイルとpythonxxx.hhp,pythonxxx.hhc,pythonxxx.hhk,pythonxxx.stpが作成されている。
pythonxxx.hhpをダブルクリックしてHTML Help Workshopを起動しコンパイルすれば,Doc\build\htmlにpythonxxx.chmファイルが作成される。
この時,locale以下に翻訳リソースがない場合,build/htmlhelpディレクトリには英語のHTMLファイルがセットされてしまう。当然,HTML Help Workshopでコンパイルしても日本語ヘルプファイルにはならない。
もし日本語化されたHTMLファイルがbuild\htmlにある場合,build\htmlhelp出来たpythonxxx.hhp,pythonxxx.hhc,pythonxxx.hhk,pythonxxx.stpを,build\htmlにコピーしてbuild\htmlのpythonxxx.hhpをダブルクリックしてHTML Help Workshopを起動しコンパイルすれば,ほぼ日本語化されたpythonxxx.chmファイルを作成することもできる。
Sphinxでは,LaTeXを使用してTeX日本語ドキュメントを出力出来て,そこからPDFファイルを作成できる。
この場合,LaTeX(W32Texを使ってる)やその他の周辺ツール,スタイルファイルなどが必要になる。
設定ファイルconf.pyのOptions for LaTeX outputで,使用するエンジンxelatexをコメントアウトする。
#latex_engine = 'xelatex'
これは,デフォルトのplatexを使うようにするため。
Sphinxのクラスにhowtoとmanualがあって,howtoが短い文書,manualが長い文書に利用されているようだ。
使用するドキュメントクラスは,デフォルト設定のhowtoにjreport,manualにjsbookが使われる。変更したい場合は,
latex_docclass = {"howto": "jsreport", "manual": "jsbook"}
のように設定する。
Pythonのドキュメントには,İ (U+0130), ı (U+0131), ſ (U+017F), K (U+212A), Ü (U+00DC), ü (U+00FC) , Є (U+0404) の非ASCii文字が含まれている。
これらをPDFで出力するために,conf.pyのプリアンプルlatex_elements['preamble']に,以下のように追加する。
latex_elements['preamble'] = r''' \authoraddress{ \sphinxstrong{Python Software Foundation}\\ Email: \sphinxemail{docs@python.org} } \let\Verbatim=\OriginalVerbatim \let\endVerbatim=\endOriginalVerbatim \usepackage[TS1,T1,T2A]{fontenc} \usepackage{lmodern} \usepackage[utf8]{inputenc} \usepackage{babel} \DeclareUnicodeCharacter{212A}{\ensuremath{\mathrm{K}}} \DeclareUnicodeCharacter{017F}{{\fontencoding{TS1}\selectfont s}} \DeclareUnicodeCharacter{0404}{\fontencoding{T2A}\CYRIE} '''
いくつかの.texファイル(library.tex,howto-logging.tex,using.tex)で,画像を読み込んでいるところでエラーが出るので,conf.pyのOptions for LaTeX outputに,以下を追加する。
latex_elements['passoptionstopackages'] = r''' \usepackage[dvipdfmx]{graphicx} '''
作成したバージョン3.7.2の日本語ヘルプファイル:python372jp.chm
新しくコメントをつける