次期nemであるnem2の開発者ドキュメントを和訳してフォークしたリポジトリで公開していましたが、このたび公式にマージされました。

このドキュメント自体が sphinx でできていたこともあり、sphinx-intl を使って翻訳を進めていました。

最初は直接 *.po ファイルを修正していたのですが、管理が大変だったので、Transifex を使い作業できるようにしました。

以下備忘録なのでいろいろ端折っていますし、もしかしたら勘違いが含まれているかもしれませんので参考程度に。

渡しているオプションなどは各々のプロジェクトで読み替えてください。

sphinx-intl のセットアップ

sphinx-intl による i18n 化については公式サイトに書いてあります。

gettext_compact = FalseFalse にすると、ページごとに *.pot が生成されるようになります。

(True だと、ドキュメント全体で1つの *.pot になるようです)

Transifex CLI のセットアップ

tx コマンドをインストールします。

$ pip install transifex-client

これはTransifexへファイルをアップロードしたりダウンロードするためのコマンドラインツールです。

インストールしたらプロジェクトディレクトリで tx init します。

途中でAPI KEYの入力を求められるので、プロジェクトの設定から発行したキーを入力します。

これにより、 ~/.transifexrc.tx/config が生成されます。

$ tx init
Welcome to the Transifex Client! Please follow the instructions to
initialize your project.

tx INFO: Creating .tx folder...
tx INFO: Creating config file...
tx INFO: Running tx config command for you...
tx INFO: No credentials file was found at /Users/yukku/.transifexrc.
tx INFO: Created /Users/yukku/.transifexrc
[?] Enter your api token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[?] Enter the path to your local source file:

[?] Enter the path to your local source file: と聞かれて、何を指定したらいいのかわからなかったので、Ctrl+cでキャンセルしました。

おそらく gettext_compact = True の場合に *.poファイルが1つにまとまった状態のプロジェクトではそれを指定するみたいです。

今回はページごとに*.poファイルが存在しますし、ディレクトリを指定してもエラーになってしまいました。

以後、特に問題なかったのでそのまま進めています。(なにを指定すればいいのかわかれば教えてください)

*.potファイルの生成、.tx/config にマッピング

*.pot を生成して、マッピングします。

$ make gettext
$ sphinx-intl update-txconfig-resources --pot-dir build/gettext --transifex-project-name=nem2-docs

Transifex へ元言語ファイルをアップロード

*.pot をTransifexプロジェクトへアップロードするのだと思います。

原文ファイルをアップしていきます。

$ tx push -s # -s は --source の意味

これで Transifex 上で編集できるようになりましたので、ひたすらサイト上で翻訳していきます。

Transifex から翻訳ファイルをダウンロード

$ tx pull -l ja # -l でダウンロードしたい言語を選べる

翻訳したファイルを Transifex プロジェクトからダウンロードします。

*.po を使って翻訳ビルドを生成

$ make -e BUILDDIR=build/ja SPHINXOPTS="-D language=ja" clean html

ビルドする場合はオプションを指定してビルドします。

元ドキュメントが更新された場合

翻訳元ドキュメントが更新され、新しい *.po ファイルが必要になった場合。

まず *.pot を作成しなおして、マッピングを更新、そしてプッシュする。

最初にやるときと同じです。

$ make gettext
$ sphinx-intl update-txconfig-resources --pot-dir build/gettext --transifex-project-name=nem2-docs
$ tx push -s

Transifex 上に翻訳対象が新しくできるので翻訳したら、あとは tx pull -l ja でダウンロードしてビルドで反映できます。

プロジェクト翻訳運用のまとめ

  1. make gettext*.pot ファイルを生成する。
  2. sphinx-intl update-txconfig-resources --pot-dir build/gettext --transifex-project-name=nem2-docs でマッピング。
  3. tx push -s で Transifex に *.pot をアップロードする。(この時点で Transifex 上で翻訳が可能)
  4. (翻訳前に履歴としてコミットしたいなら以下の2ステップを実行)
  5. tx pull -l ja で Transifex から *.po をダウンロードする。
  6. プロジェクトへ翻訳前ファイルの *.po をコミットする。
  7. Transifex 上で翻訳をする。
  8. tx pull -l ja で Transifex から *.po をダウンロードする。
  9. 翻訳したファイルの変更が現れるのでコミットする。
  10. 以下繰り返し

原文に更新があった場合

  1. make gettext*.pot ファイルを生成する。
  2. sphinx-intl update-txconfig-resources --pot-dir build/gettext --transifex-project-name=nem2-docs で再マッピング。
  3. tx push -s で Transifex に *.pot をアップロードする。
  4. 以下繰り返し

ブランチとしてプッシュする

tx push -s -b foobar のように -b, --branch オプションをつけると、gitのようにブランチとしてプッシュできる。

tx pull -l ja -b foobar ダウンロードするときにも指定できる。

push/pull ともに --parallel というオプションがあり、言語ファイルを並列でアップ・ダウンロード処理してくれます。

しかし、今回数百ファイルの*.potがあり、試しに何度か叩いていたときに、

オプションを使っていたら、APIの利用制限に引っかかってしまいまいた。

Be careful when using this option with many files as it may cause you to hit your API rate limits.

とオプションの説明にあるように、このオプションによって結構頻繁にエラーが起こるので、ファイル数が多いでも、仕方ないですがこのオプションを使わずに利用するしかなさそうです。