この文書では PEP 545 の accept に伴う新ワークフローの設計・運用について記述する。

2017/12/22 時点での翻訳プロジェクトの責務は次の2点。

• カタログテンプレート (.pot ファイル) の生成、翻訳サービスへのアップロード、履歴管理
• カタログ (.po ファイル) の翻訳サービスからの取得とpython-docs-ja への push

翻訳サービスは引き続き Transifex を利用する。CI サービスは Travis CI を利用する。

GitHub への push は ssh 経由でDeploy key の仕組みを利用する。(Travis CI で GitHub の Private Access Token がログに表示されてしまったことがあるため。)そのため Deploy key 用の秘密鍵を CI のビルド環境へ送り込む必要がある。

Transifex プロジェクトへの pull/push では API Token を設定した .transifexrc ファイルを使用する。この .transifexrc ファイルは内容を知られること無く CI のビルド環境へ送り込む必要がある。

これらの秘匿すべきファイルをビルド環境へ送り込むために、openssl コマンドを使用する。

鍵ファイル名の末尾に使用するブランチを追記しておき、問題が起きたときの対処の範囲を狭めておく。.transifexrc はファイル名が決められているため、ファイルの内容の編集で対応する。

ちなみに、travis encrypt-file は1つのレポジトリに対して1組の鍵しか設定できないため、Python バージョンごとにブランチがある python-docs-ja には向いていない。そのため openssl コマンドによる暗号化を選択している。

openssl コマンドで必要となる鍵 (64桁の16進文字列) と初期ベクトル (64桁の16進文字列) は何かしらの方法で暗号論的に安全なものを生成する。例えば、次のコマンドで生成する。

hexdump -n 16 -e'4/4 "%08X" 1 "\n"' /dev/random

以下は Python 3.6 での暗号化ファイルの作成例。鍵と初期ベクトルは Travis CI の環境変数として保存しておく。(Travis CI の環境変数はログに出力されず、プルリクエストでは利用できなくなっているため、秘匿情報を保存するのに使える。)

tar -cf secrets_3.6.tar .transifexrc .ssh/python-docs-ja_3.6 .ssh/cpython-doc-catalog_catalog-3.6openssl aes-256-cbc -K${鍵} -iv${初期ベクトル} -in secrets_3.6.tar -out secrets_3.6.tar.encmv secrets_3.6.tar.enc .../python-docs-ja/

secrets_3.6.tar.enc を commit して準備は完了。

復号コマンドは次の通りで、これは.travis.yml の手順に含めておく。注意: 過って push してしまうのを防ぐためsecrets_3.6.tar を CI 環境のローカルレポジトリ内に出力しないこと。

openssl aes-256-cbc -K${鍵} -iv${初期ベクトル} -in /path/to/secrets_3.6.tar.enc -out~/secrets_3.6.tar -d

以下の順番で1日1回の頻度で実行する。日次実行の仕組みは Travis CI のcron job 機能を利用する。(Circle CI も検討したが、1500h/month のビルド時間の制限に収まらなかったため断念した。)

1. カタログの更新と反映
2. カタログテンプレートの生成、 Transifex へのアップロード、履歴管理

この順序にした理由は、カタログテンプレートのアップロードで翻訳率が下がる可能性があるため。

カタログはhttps://github.com/python/python-docs-ja レポジトリで管理する。

• python-docs-ja レポジトリ
  • 2.7 ブランチ
  • 3.6 ブランチ

cpython-doc-catalog # cpython-doc-catalog を clone  `- Doc/       `- locales/            `- .tx/config            `- ja/LC_MESSAGES/ # python-docs-ja への symlinkpython-docs-ja # python-docs-ja を clone  `- about.po     ...

次の手順の CI ビルドを定期的に実行する。（ここでは Python 3.6 を例に取る。）

1. python-docs-ja レポジトリの 3.6 ブランチを clone
2. cpython-doc-catalog レポジトリの catalog-3.6 ブランチを clone
3. cpython-doc-catalog の Doc/locales/ja/LC_MESSAGES ディレクトリを python-docs-ja への symlink として作成
4. 仮想環境を作成し、依存関係をインストール
5. Transifex の Python 3.6 プロジェクトからカタログをダウンロード
6. カタログを python-docs-ja レポジトリの 3.6 ブランチに push

1日に1回

https://github.com/python/cpython を fork したhttps://github.com/python-doc-ja/cpython-doc-catalog レポジトリで管理する。

• cpython レポジトリ
  • 2.7 ブランチ
  • 3.6 ブランチ
• cpython-doc-catalog レポジトリ
  • catalog-2.7 ブランチ (2.7 ブランチから分岐したブランチ)
  • catalog-3.6 ブランチ (3.6 ブランチから分岐したブランチ)

cpython-doc-catalog # cpython-doc-catalog を clone  `- Doc/       `- locales/            `- .tx/config # transifex-client のプロジェクト設定ファイル            `- pot/       # カタログテンプレートのディレクトリ

次の手順の CI ビルドを定期的に実行する。（ここでは Python 3.6 を例に取る。）

1. cpython-doc-catalog レポジトリの catalog-3.6 ブランチを clone
2. 仮想環境を作成し、依存関係をインストール
3. cpython レポジトリの 3.6 ブランチを pull
4. カタログテンプレートを生成
5. Transifex の設定ファイルを作成
6. 生成したカタログテンプレートを Transifex の Python 3.6 プロジェクトにアップロード
7. 生成したカタログテンプレートを cpython-doc-catalog レポジトリの catalog-3.6 ブランチに push

1日に1回