Pythonのドキュメントの日本語化とヘルプファイル anchor.png

私はPython初心者で,Pythonの公式ドキュメントをマニュアルとしてよく見る。
公式オリジナルの英語版が https://docs.python.org/3/ で公開されていて,その日本語に翻訳されたものが https://docs.python.jp/3/ で公開されている。

PythonをインストールするとWindowsのヘルプファイルも提供されるが,日本語翻訳したものは公式にはリリースされていないみたい。

一応,Python Japanese Environmentで,Python 2.7の日本語Windowsヘルプファイルがあるのだが,なぜかエラーが毎回表示されてしまう。また,最新のバージョンのものは残念ながら見つからない。

そこで,日本語翻訳されたWindowsのヘルプファイルを作成してみることにした。

Pythonドキュメント日本語訳プロジェクトの活動のおかげで,日本語訳のリソースは手に入れることが出来る。
これを使用して,日本語のPythonのヘルプファイルを作成してみる。

Page Top

ソースコードと日本語リソースを用意する anchor.png

まず,Pythonのドキュメントから日本語のドキュメント(HTML)を作成してみる。

Page Top

ビルドに必要なツールを用意する anchor.png

ドキュメントを作成するのに必要なツールSphinx(Pythonで動作する)やTransifex(翻訳プロジェクト)などを,インストールする。

> pip install sphinx
> pip install sphinx-intl
> pip install blurb
> pip install transifex-client
Page Top

Pythonのソースコードを準備 anchor.png

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
Page Top

Sphinxの設定ファイルを修正 anchor.png

Sphinxを使用して日本語ドキュメントが出力されるように,conf.pyファイルのGeneral configurationのどこかに,以下の追加・修正をする。

language = 'ja'
locale_dirs = ['locale/']
gettext_compact = False
 :
 :
today_fmt = '%m/%d/%Y'
Page Top

翻訳済みリソースをTransifexからダウンロードする anchor.png

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ファイルがダウンロードできる。

Page Top

Pythonドキュメント日本語訳プロジェクトのリソースを使う場合 anchor.png

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

とすれば良いと思われるが,残念ながらまだリポジトリにアップされていない。(翻訳作業自体は進んでいる。)

Page Top

日本語ドキュメント(HTML)を作成 anchor.png

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に作成される。

Page Top

Windowsのヘルプファイルchmを作成する anchor.png

HTMLのドキュメントが作成出来れば,Windowsで使われるヘルプファイルである.chmファイルを作成できる。

作成するには,Microsoftの HTML Help Workshop が必要になる。

Page Top

.chmファイルを作成する anchor.png

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ファイルを作成することもできる。

Page Top

LaTeXを使ってPDFファイルを作成する anchor.png

Sphinxでは,LaTeXを使用してTeX日本語ドキュメントを出力出来て,そこからPDFファイルを作成できる。
この場合,LaTeX(W32Texを使ってる)やその他の周辺ツール,スタイルファイルなどが必要になる。

設定ファイルconf.pyOptions 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.pyOptions for LaTeX outputに,以下を追加する。

latex_elements['passoptionstopackages'] = r'''
\usepackage[dvipdfmx]{graphicx}
'''
Page Top

texファイルを作成して,さらにpdfファイルを作成する anchor.png

DocディレクトリにMakefile等があるので,それを使ってtexファイルを作成する。

> make latex PAPER=a4

この時,文書サイズをA4かletterか指定できる。
うまくいくと,build/latexディレクトリに.texファイルが作成されている。

texファイルからPDFファイルに変換してみる。

> cd build/latex 
> make all-pdf-ja

これで,うまく行けばPDFファイルが作成される。

Page Top

作成した日本語ドキュメント anchor.png

作成したバージョン3.7.2の日本語ヘルプファイル:filepython372jp.chm


コメント一覧

新しくコメントをつける

題名
ゲスト名   :
投稿本文
より詳細なコメント入力フォームへ

Front page   Freeze Diff Backup Copy Rename Reload   New Page Page list Search Recent changes   Help   RSS of recent changes (RSS 1.0) RSS of recent changes (RSS 2.0) RSS of recent changes (RSS Atom)
Counter: 74, today: 1, yesterday: 0
Last-modified: 2019-02-21 (Thu) 13:46:27 (JST) (115d) by yuji
ユーザ名:

パスワード:



パスワード紛失

新規登録