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

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

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

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

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

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


```powershell: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のリポジトリ](https://github.com/xlwings/xlwings)をフォークします。赤丸で囲った部分Forkボタンをクリックすればフォークできます。
<img width="771" alt="xlwingsのフォーク.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/239172/b974bf28-03df-3ed1-ad09-e1f3c0ce44a1.png">

フォークの説明は以下を参照。
[Github で Fork して PullRequest を送るのはこんなに簡単](https://qiita.com/YumaInaura/items/acff806290c8953d3185)

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


## potファイル、poファイルの生成
Powershellで以下を実行。

```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: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](https://marketplace.visualstudio.com/items?itemName=tht13.html-preview-vscode)を使って編集しているところ。灰色背景のテキスト（ctrl+1とか）はペイン間を移動するショートカットです。
![2020-04-13.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/239172/11d87c78-efa5-6d6a-8a4d-4db20b65239f.png)

きりのいいところで、編集した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]ボタンをクリックします。
<img width="753" alt="xlwingsのプルリクエスト.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/239172/de445e56-3a88-f98e-4df5-912df85acc60.png">
次の画面で適当にメッセージを入れて、Pull Requestを送ります。本家がmergeしてくれれば、公式ドキュメントに反映されます。意外と簡単！


# 参考
http://www.sphinx-doc.org/ja/master/usage/advanced/intl.html