[Deprecated] HowToUpdateOriginal - python-doc-ja/python-doc-ja Wiki

この手順は管理者が行うものです。

この手順は cpython-doc-intl, py36-locale, py36 に対するものです。

Python 3.6 の翻訳を行う場合を例として解説します。 どの手順もレポジトリの clone から始めますので、既存のローカルレポジトリを使って作業する場合は適宜読み替えてください。 (例えば git checkout -t rep1/hogegit checkout hoge && git pull rep1 hoge に読み替えるなど。)

レポジトリ・ブランチ構成

この解説で出てくるレポジトリとそのブランチの一覧です。

ツールのインストール

Transifex を操作するクライアントツールをインストールします。

$ pip install transifex-client

Transifex のアカウント情報を ~/.transifexrc に記入します。

[https://www.transifex.com]
hostname = https://www.transifex.com
token = 
username = <ユーザー名>
password = <パスワード>

pot ファイルを作成するためのツールをインストールします。

$ pip install sphinx-intl

既存のプロジェクトの更新

既に Transifex に翻訳プロジェクトが作成済みで、そこに登録してある原文を更新する際の手順です。

作業に必要なブランチをローカルレポジトリに作成しておきます。

$ git clone https://github.com/python/cpython.git
$ cd cpython
$ git remote add intl https://github.com/python-doc-ja/cpython-doc-intl.git

$ git clone https://github.com/python-doc-ja/py36-locale.git Doc/locale

原文の更新

まずは新しくなっている原文を本家のブランチから取得します。 (既存のローカルレポジトリを使う場合は、ローカルブランチを最新の状態にしてください。)

最新の状態になった翻訳プロジェクト用のブランチはリモートレポジトリに上げておきます。

$ git fetch intl
$ git checkout -t intl/intl-3.6
$ git merge origin/3.6
$ git push intl intl-3.6

(pot ファイルの作成は python-docs-ja に対する CI の責務となったため、ここでは作業の必要はありません。)

新バージョン対応

Python の新しいバージョン (執筆時点では 3.6) が出た時に行う手順です。

TODO: Transifex プロジェクトの作成の説明を別ページに切り出す

Transifex にプロジェクトを作る

2017年2月17日時点で、翻訳プロジェクトに様々な言語が登録されるようになっているため、プロジェクトの URL 設定は python-36 のような言語に依存しないプロジェクト名にしています。 細かい設定は直前のプロジェクトの設定などを参考にしてください。

python-doc-ja という組織でプロジェクトを作成後、翻訳メモリを共有するために、組織の管理画面で新しく作ったプロジェクトを翻訳メモリのグループに追加します。 次に、プロジェクトの管理画面で翻訳メモリから自動で翻訳文を埋める設定をします。

これらの設定をした後に pot ファイルをアップロードすることで、前のバージョンから変わってない部分が自動で埋められるようになります。

カスタマイズ部分のマージ

日本語プロジェクト向けにテンプレート等をカスタマイズしているので、それを取り込みます。

まず差分のパッチを作成します。

$ git clone https://github.com/python/cpython.git
$ cd cpython
$ git remote add intl https://github.com/python-doc-ja/cpython-doc-intl.git
$ git checkout -t origin/3.5
$ git fetch intl
$ git checkout -t intl/intl-3.5
$ git merge 3.5
$ git diff 3.5..intl-3.5 > intl.patch

作成したパッチを新しいバージョンブランチに適用します。 新しく作成された翻訳プロジェクト用のブランチはリモートレポジトリに上げておきます。

$ git checkout -t origin/3.6
$ git checkout -b intl-3.6
$ patch -p1 < intl.patch
$ git status
$ git add ... (patch ファイル以外を add)
$ git commit
$ git push --set-upstream intl intl-3.6

翻訳ファイルを管理するレポジトリを新規に作成し、所定の位置に clone します。

$ git clone https://github.com/python-doc-ja/py36-locale.git Doc/locale

pot ファイルを作り直します。

$ cd Doc
$ make gettext

.tx/config の設定

.tx/config の内容が前のバージョンのままになっているので、作り直します。 --transifex-project-name オプションには Transifex プロジェクトの URL の設定で使っている名前を指定します。 更新した pot と .tx/config はリモートレポジトリに上げておきます。

$ cd locale
$ rm -rf .tx
$ sphinx-intl create-txconfig
$ sphinx-intl update-txconfig-resources --transifex-project-name=python-36 --locale-dir . --pot-dir pot
$ git add pot
$ git add .tx/config
$ git commit -m 'Update pot and .tx/config'
$ git push

transifex への push

作成したリソースを Transifex に push します。 transifex-client の以前のバージョンにはバグがあったので、0.11 以降を使ってください。

$ tx push -s

Transifex でどれか適当なリソースの翻訳画面を開いて、翻訳メモリが共有されているかを確認してください。 変更の無い原文であれば既に訳文があるはずで、そうでなくてもある程度似た原文があれば、その訳文が提示されているはずです。 翻訳メモリからの訳文の反映は少々時間がかかるようです。

継続的デリバリの準備

2017年2月17日時点でドキュメントは Travis CI を利用して定期的にビルドしています。

一連のビルド処理の一部として py36-locale が Travis CI で動作するための設定ファイル .travis.yml を、前のバージョンのものを参考に作成します。 コピーした設定ファイルに含まれるバージョン番号を書き換え、ビルド成果物を管理する py36 レポジトリへ git push するための Personal access token を設定します。 トークンを python-doc-ja の管理者アカウントで払い出し、 travis encrypt で暗号化します。

$ gem install travis
$ travis encrypt -r 'python-doc-ja/py36-locale' GH_TOKEN=<払い出したトークン>

secure: の後ろに出力された文字列を .travis.yml に設定して、リモートレポジトリに上げます。

$ cd Doc/locale
$ emacs .travis.yml
...
env:
  global:
    secure: <暗号化文字列>
...
$ git add .travis.yml
$ git commit -m 'Add .travis.yml'
$ git push

ビルドした結果のファイル群を管理するための py36 レポジトリを作成します。 アンダースコアで始まるファイルやディレクトリが無視されないよう Jekyll を無効化しておきます。

$ git clone https://github.com/python-doc-ja/py36.git
$ cd py36
$ touch .nojekyll
$ git add .nojekyll
$ git commit -m '.nojekyll'
$ git push

このレポジトリは GitHub Pages に設定し、 master ブランチのプロジェクトルートを公開するようにします。

一連のビルドの起点となる cron は python.jp サーバーで動かしています。 python-doc-ja の issue 762 を参考に、 Python 3.6 用のスクリプトを作成し cron に登録します。 最後に python-doc-ja の Travis CI で py36-locale を有効にして作業は完了です。

無事ドキュメントが https://python-doc-ja.github.io/py36/ で公開されるのを待ちましょう。