NewVersion

新バージョン対応

ここでは、メジャーバージョンまたはマイナーバージョンが上がった新バージョン (執筆時点では 3.10) のベータ版が出たときにどんな作業を行うかを説明します。新バージョンがリリースされるときまでに、以下に書かれている作業が完了していることが望ましいです。新バージョンのブランチが切られたときからリリースされるまでの数カ月の間で作業をしましょう。

以下では 3.10 のリリースに伴う作業を例とします。それ以外のバージョンでは適宜読み替えてください。新バージョンが出たことにより、最新ではなくなったバージョン (3.10 が出たときの 3.9 のこと) を「前最新バージョン」と呼ぶことにします。

事前調整

日本語翻訳チームが使っている Transifex project は他の言語の翻訳チームも使っています。 Transifex の設定を修正する前に Doc-SIG や Transifex の Announce 機能を使い必要な連絡を行うこと。

レポジトリベースの構成要素

翻訳プラットフォームは次の要素から構成されています。

cpython レポジトリ
- CPython 本家のレポジトリ
cpython-doc-catalog レポジトリ
- 翻訳テンプレートファイルの管理
Transifex プロジェクト (python-doc Organization)
- 翻訳サービス
python-docs-ja レポジトリ
- 翻訳ファイルの管理

翻訳が処理される流れは次のようになっています。

cpython
↓
↓ fork
↓
cpython-doc-catalog
↓
↓ 翻訳テンプレートファイルのアップロード
↓
Transifex
↓
↓ 翻訳ファイルのダウンロード
↓
python-docs-ja

原文のブランチ構成

原文と翻訳テンプレートファイル (.pot ファイル) は cpython レポジトリを fork した cpython-doc-catalog レポジトリで管理しています。ブランチ構成は次の通りです。

https://github.com/python/cpython.git # 本家のレポジトリ
- main # 最新の開発バージョン
- 3.10
- 3.9
- ~~2.7~~
https://github.com/python-doc-ja/cpython-doc-catalog.git # 原文と翻訳テンプレートファイルを管理するレポジトリ
- catalog-3.10 # cpython の 3.10 ブランチから分岐したブランチ
- catalog-3.9 # cpython の 3.9 ブランチから分岐したブランチ
- ~~catalog-2.7 # cpython の 2.7 ブランチから分岐したブランチ~~

Python 3.10 の beta 版が出るタイミングで本家のレポジトリの main から新たに 3.10 ブランチが切られ、 main ブランチは次のバージョンの開発に移ります。

それを受けて cpython-doc-catalog レポジトリで catalog-3.10 ブランチを新たに作成します。

Transifex のプロジェクト構成

翻訳を管理するサービスは Transifex を使っています。 Transifex はプロジェクトという単位で翻訳を管理し、 Transifex のプロジェクト名にある数値（例: Python 3.9 の「3.9」）が Python のマイナーバージョン (例: Python 3.9) に対応しています。

プロジェクト名：Python (プロジェクト URL: python-newest)
- 最新の Python ドキュメントの翻訳管理
- 最新バージョンは常にこのプロジェクト
プロジェクト名：Python x.y (プロジェクト URL: python-xy)
- バージョン x.y の Python ドキュメントの翻訳管理
- 最新以外のバージョンはこのプロジェクト

訳文のブランチ構成

翻訳ファイル (.po ファイル) は python-docs-ja で管理しています。ブランチ構成は次の通りです。

https://github.com/python/python-docs-ja.git # 翻訳ファイルを管理するレポジトリ
- 3.10
- 3.9
- ~~2.7~~

この構成要素それぞれで順次新バージョン対応を行っていきます。

ツールのインストール

まずは作業環境に必要なツールをインストールします。

$ pip install transifex-client sphinx-intl blurb

Transifex のアカウント情報を ~/.transifexrc に記入します。 <TX_TOKEN> は右上のユーザーアイコンから User settings に進み、 API token をクリックして token を取得します。

[https://www.transifex.com]
api_hostname = https://api.transifex.com
hostname = https://www.transifex.com
password = <TX_TOKEN>
username = api

秘密鍵の取り扱い

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

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

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

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

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

前最新バージョンの作業

Transifex の前最新バージョン用プロジェクトの作成

前最新バージョンで必要な作業は主に、これまで「python-newest」となっていたところを「3.9」に変えることです。

新しいバージョンの翻訳を始めるときは、次のように対応する Python のバージョンを変更します。 Transifex のプロジェクト名と、それに対応する Python バージョンを括弧で括って表記します。

Python 3.10 の翻訳を開始する場合
- (新規作成) -> Python (3.10) ※ 最新バージョン用
- Python -> Python 3.9 (3.9) ※ 前最新バージョン用
- ~~Python 3.5 (3.5) -> Python 3.5 (3.5)~~ ※ 対象外バージョン
- ~~Python 2.7 (2.7) -> Python 2.7 (2.7)~~ ※ 対象外バージョン

最新バージョンの 3.10 用の Transifex プロジェクトを作成します。 2017/02/17時点で、翻訳プロジェクトに様々な言語が登録されるようになっているため、プロジェクトの URL 設定は python-36 のような言語に依存しないプロジェクト名にしています。プロジェクトの Settings メニューにある細かい設定は他のプロジェクトの設定などを参考にしてください。

プロジェクトの管理画面の Workflow タブにある Translation Memory Fill-up を有効にし、翻訳メモリから自動で翻訳文を埋める設定を保存するのを忘れないでください。右上の「Python document transla...」から「Organazation Settings」メニュー > 左のパネルの「Translation memory」と移動する。翻訳メモリを新しく作ったプロジェクト共有するために、翻訳メモリのグループ (グループ名: global) に追加します。

ref. https://docs.transifex.com/setup/translation-memory/enabling-autofill

前最新バージョンの Continuous Delivery 設定変更

前最新バージョンの Travis CI 設定を変更します。

python-docs-ja の 3.9 ブランチにある .travis.yml に設定されている環境変数 TRANSIFEX_PROJECT の値を次のように修正します。

env:
  global:
    # branch name of python-docs-ja repository
    - DOCS_BRANCH=3.9
    # branch name of cpython repository
    - CPYTHON_BRANCH=3.9
    # branch name of cpython-doc-catalog repository
    - CATALOG_BRANCH=catalog-3.9
    # Transifex project name
    - TRANSIFEX_PROJECT=python-39

.travis.yml の修正を push することで Continuous Delivery のジョブが動きます。正常終了することを見届けて、前最新バージョンに対する対応は完了です。

新バージョンの作業

原文のアップロード

新たに作成した python プロジェクトの中身が空なので、翻訳テンプレートファイルをアップロードします。

まずは cpython-doc-catalog レポジトリの master ブランチ（既存のブランチであれば何でも良い）を clone し、 python/cpython レポジトリの 3.10 ブランチから、 cpython-doc-catalog レポジトリに catalog-3.10 ブランチを作成します。

次に python-docs-ja レポジトリを cpython-doc-catalog/Doc/locales/ja/LC_MESSAGES に clone し, orphan ブランチとして 3.10 ブランチを作成し,次のような構成を作ります。

cpython-doc-catalog # cpython-doc-catalog の catalog-3.10 ブランチを作成しておく
  `- Doc/
       `- locales/
            `- .tx/config
            `- ja/LC_MESSAGES/ # python-docs-ja の 3.10 ブランチを作成しておく
                 `- about.po
                 ...

LC_MESSAGES ディレクトリを python-docs-ja ディレクトリへの symlink とすると訳文のアップロードに失敗する (Transifex client 0.13.3 で確認) ので直接 clone する。

$ git clone --branch main git@github.com:python-doc-ja/cpython-doc-catalog.git
$ cd cpython-doc-catalog
$ git remote add upstream git@github.com:python/cpython.git
$ git fetch upstream 3.10
$ git switch -c catalog-3.10
$ git commit --allow-empty -m 'Create branch catalog-3.10'
$ git merge upstream/3.10
$ git push --set-upstream origin catalog-3.10

Transifex のプロジェクト設定ファイルである .tx/config を python プロジェクト用に作り直し、potファイルの一覧を作成します。

$ cd ${BASEDIR}/cpython-doc-catalog/Doc/locales
$ rm -rf .tx
$ sphinx-intl create-txconfig # .tx/config の作成
$ cd .. # Doc に移動
$ make build ALLSPHINXOPTS="-E -b gettext -D gettext_compact=0 -d build/.doctrees . locales/pot" # pot ファイルの生成
$ cd locales
$ sphinx-intl update-txconfig-resources --transifex-project-name=python-newest --locale-dir . --pot-dir pot # potファイル一覧の作成

設定ファイルが作成できたら原文をアップロードします。

$ tx push -s --parallel

翻訳メモリの設定が効いていることを確認するために、しばらく時間を置いた後、Transifex の画面で訳文が当たっていることを確認します。 (いつまで待っても翻訳メモリが適用されない場合は、設定漏れが無いか Transifex の前最新バージョン用プロジェクトの作成を見返してみてください。)

注意: .tx/config の変更は cpython-doc-catalog レポジトリに push しないでください。 .tx/config は Continuous Delivery のジョブで更新されます。

訳文の新バージョン対応

訳文の履歴の管理は Transifex の責務となるため、訳文のブランチは他のブランチと関係を持たない形で作成します。

$ git clone --branch 3.9 git@github.com:python/python-docs-ja.git
$ cd python-docs-ja
$ git checkout --orphan 3.10  # 新しく 3.10 ブランチを作成
$ git rm --cached -r *      # ドットファイル以外の全てのファイルをいったん削除
$ git add scripts README.md # 残すものは個別に追加

用語集 (glossary) の共有

右上の「Python document transla...」から「Organazation Settings」メニュー > 左のパネルの「Glossary」と移動する。訳語のブレを防ぐために既存のglossary「python_global (English)」にプロジェクトを追加する。

CD 設定の新バージョン対応

python-docs-ja レポジトリでは Travis CI の設定ファイルも管理しています。

さきほどのコマンドを実行したなら、3.9 ブランチのビルド用のファイル群が残っているはずなので、これらを修正して 3.10 用にします。

2018/04/01 時点で、修正すべき箇所は4つの環境変数、ビルド対象のブランチ名、 openssl コマンドのオプションにある2つの変数名で、次のように修正します。

2019/09/01 時点で、修正すべき箇所は

.travis.yml
- 4つの環境変数
- ビルド対象のブランチ名
scripts ディレクトリ以下のファイル
- ファイル名
- ファイルに含まれる openssl コマンドのオプションにある2つの変数名
GitHub Actionsの設定ファイル
- on.pull_request.branches に設定されているバージョン名

で、次のように修正します。 (環境変数 TRANSIFEX_PROJECT の値を python-newest にしているのに注意してください。)

.travis.yml

...
branches:
  only:
  - 3.10
env:
  global:
    # branch name of python-docs-ja repository
    - DOCS_BRANCH=3.10
    # branch name of cpython repository
    - CPYTHON_BRANCH=3.10
    # branch name of cpython-doc-catalog repository
    - CATALOG_BRANCH=catalog-3.10
    # Transifex project name
    - TRANSIFEX_PROJECT=python-newest
...

scripts/push/main.sh

...
bash ${TRAVIS_BUILD_DIR}/scripts/${build_type}/prepare-build_3.10
...

scripts/push/prepare-build_3.9 → scripts/push/prepare-build_3.10

...
openssl aes-256-cbc -K ${encryption_310_K} -iv ${encryption_310_iv} -in "${BASEDIR}/python-docs-ja/secrets_${DOCS_BRANCH}.tar.enc" -out ~/secrets_${DOCS_BRANCH}.tar -d
...

.github/workflows/...yml

name: XXX

on:
  pull_request:
    branches: [ "3.10" ]
    types:
...

cpython-doc-catalog レポジトリと python-docs-ja レポジトリへ push するのに使う SSH 鍵を、それぞれ cpython-doc-catalog_catalog-3.10 、 python-docs-ja_3.10 という名前で作成します。この鍵をそれぞれのレポジトリの Deploy key として登録します。 Transifex で Python 3.10 プロジェクト用の API Token を生成し、 ~/.transifexrc に次のように設定します。

[https://www.transifex.com]
api_hostname = https://api.transifex.com
hostname = https://www.transifex.com
password = <TX_TOKEN>
username = api

秘密鍵の取り扱いを参照し、秘密鍵を暗号化したファイルを作成します。

注意: 暗号化していない秘密鍵の値を含んだファイルをレポジトリに push しないよう注意してください。過ってレポジトリに commit しないように .gitignore ファイルに記載しておきましょう。もし過って push していたことに気付いたときは、すぐに Deploy key の設定を無効にし、レポジトリから該当ファイルを削除してください。

.gitignore

secrets_3.10.tar

ここまでの作業結果を python-docs-ja レポジトリに push して作業は完了です。この push がトリガーとなり Tranvis CI のジョブが起動します。

$ emacs .gitignore
$ cat .gitignore
## => secrets_3.10.tar
$ emacs README.md # 適宜修正
$ git add .gitignore README.md secrets_3.10.tar.enc .travis.yml
$ git commit -m 'Create branch 3.10'
$ git push --set-upstream origin 3.10

python-docs-ja レポジトリに 3.10 ブランチが作られていない時点では、 Travis CIへの環境変数の登録で 3.10 ブランチを指定できないので敢えて登録しておきません。

当然、Travis CIのビルドに失敗するので、「鍵」と「初期ベクトル」を登録して再度実行します。秘密鍵を暗号化するときに使用した「鍵」と「初期ベクトル」は Travis CI プロジェクトに、 encryption_310_K 変数および encryption_310_iv として登録してください。

初回のビルドでジョブが正常終了することを見届けたら、 3.10 ブランチを cron job に登録し、 python-docs-ja のデフォルトブランチを 3.10 に設定します。最後に、Travis CIのCron Jobsの設定をしたら、最新バージョンに対する対応は完了です。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly