Sphinxの多言語対応機能で、xlwingsのドキュメントを日本語化する

VBAアレルギーのため、xlwingsを社内で普及させたいが、日本語ドキュメントがない。調べてみたら、公式ドキュメントはどうやらSphinxとかいうやつで書かれているよう。右上にEdit on GitHubと書かれているので、翻訳したものをプルリクエストしたら日本語化（まだ一部）されたよという話。

興味を持ってくれた人がいたら、一緒に翻訳しましょう。

環境構築

Windows 10前提です。必要なものは以下のとおり。Sphinxを除き、インストール方法は他の人の投稿に譲ります。

• Python
• Sphinxと関連パッケージ
• Git
• GitHubアカウント
• テキストエディタ（VScodeとか）
• TortoisGit（Gitに慣れている人は不要）

Sphinxと関連パッケージはpipでインストールします。

PowerShell

> pip install sphinx                   #Anacondaだと最初から入っている
> pip install sphinx-intl              #関連パッケージのインストール
> pip install sphinxcontrib-napoleon   #関連パッケージのインストール(xlwing以外のドキュメントだと要らないかも)
> pip install sphinxcontrib-httpdomain #関連パッケージのインストール(xlwing以外のドキュメントだと要らないかも)
> pip install sphinx_rtd_theme         #関連パッケージのインストール(xlwing以外のドキュメントだと要らないかも)

作業

フォーク、クローン

GitHubにログインして、xlwingsのリポジトリをフォークします。赤丸で囲った部分Forkボタンをクリックすればフォークできます。

フォークの説明は以下を参照。
Github で Fork して PullRequest を送るのはこんなに簡単

フォークしたら、TortoiseGitでローカルに保存します（クローン）。適当なフォルダー（ここではC:\githubとします）で、右クリックメニューから[Git Clone...]を選択→TortouseGitの画面上で先ほどフォークした自分のリポジトリのURLを入力し[OK]をクリックすれば、クローンされます。

potファイル、poファイルの生成

Powershellで以下を実行。

PowerShell

> cd c:\github\xlwings\docs #クローン先に合わせて変更してください
> .\make.bat gettext
> sphinx-intl update -p ./_build/locale -l ja

C:\github\xlwings\locales\ja\LC_MASSAGESにpotファイル、poファイルが生成されます。

翻訳

poファイルに日本語訳を入力する。例えば、トップページを翻訳するにはindex.poファイルの

index.po（翻訳前）

...
#: ../../index.rst:2
msgid "xlwings - Make Excel Fly!"
msgstr ""
...

msgstr ""部分に日本語訳を入力する。

index.po（翻訳後）

...
#: ../../index.rst:2
msgid "xlwings - Make Excel Fly!"
msgstr "xlwings - 翔べ！Excel"
...

（もえあがーれー、もえあがーれー、もえあがーれー　エクセルー）

HTMLファイルで確認

以下を実行。

PowerShell

> set-item env:SPHINXOPTS "-D language=ja" #ユーザー毎に一度だけ設定
> .\make.bat html

set-item env:SPHINXOPTS "-D language=ja" をセッション毎に実行するのが面倒であれば、[System.Environment]::SetEnvironmentVariable("SPHINXOPTS", "-D language=ja", "User")を実行し環境変数として保存。
C:\github\xlwings\docs_build\htmlにHTMLファイル一式が生成されるので、index.htmlファイルをブラウザーで確認。修正が必要であれば、再度poファイルを編集し、.\make.bat htmlを実行します。

以下は、VScodeと拡張機能HTML Previewを使って編集しているところ。灰色背景のテキスト（ctrl+1とか）はペイン間を移動するショートカットです。

きりのいいところで、編集したpoファイルを管理対象に追加し、commitしておきましょう。commitの方法は以下を参照。
http://www.aise.ics.saitama-u.ac.jp/~gotoh/DailyWorkTortoiseGit.html#toc6

プルリクエスト

まずはローカルの作業をGitHubに反映。GitHubC:\github\xlwingsで、右クリックメニューから[TortoiseGit]→[Push...]を選択→TortouseGitの画面の[OK]をクリックすれば、ローカルの作業がGitHubに反映されます。
いよいよPull Request。自分のリポジトリを開き、下の画面で赤丸で囲った[New pull request]ボタンをクリックします。

次の画面で適当にメッセージを入れて、Pull Requestを送ります。本家がmergeしてくれれば、公式ドキュメントに反映されます。意外と簡単！

参考