(ここの文字サイズ大きくする、マウスをレーザーポインタにする)
こんにちは、今日は私のセッションに来ていただいてありがとうございます。
このセッションでは「~」を紹介したいと思います。
伝統の「おまえ誰よ」から。
清水川です。
オープンソースで3つの活動をしています。
1. Sphinx co-maintainer since the end of 2011.
2. organize Sphinx-users.jp users group in Japan.
3. member of PyCon JP Committee.
BePROUDで働いています。
弊社では、主にDjangoやPyramidなどを使ってWebアプリケーション開発を行っています。
最近、Pythonトレーニング事業、Python技術サポート事業も始めました。
自宅勤務が週5日までOK、スタンディングデスクあり、ラジオ体操ありの会社です。
本題に入る前に。質問があります。
どのくらいの人がオープンソースソフトウエアを使っていますか?
-> 10, 20, ... ありがとうございます。
A-> 明らかにほとんどの人がOSS使ってるようですね。B-> あれ、意外と少ないですね。半分くらいでしょうか。
次の質問です。
自分はOSSに貢献している、という人はどのくらいいますか?
-> 1, 2, ... ありがとうございます。
A-> かなり少なくなりましたね。N人くらいでしょうか。B-> おー、けっこう多くの人が手を挙げてくれました。N人くらいですね。
私としては、OSSを使う事、それを人に勧めることが最初の貢献なのかなと思っています。
ですので、最初に手を挙げてもらった、OSS使ってる方はもう1歩目の貢献をしているのかなと思います。
次の質問です。
多くのOSSドキュメントが英語で提供されています。
これらを日本語など普段使っている言語に翻訳することは他の開発者の助けになると思いますか?
10, 20,... ありがとうございます。
A-> ほとんどの人がそう思う、ということですね。私もそう思います。
B-> あれ、みんな手を挙げるかなと思ったんですが・・、みんな英語読めってことですかね。厳しめですねー
私が聞いた話では、日本の技術者はググって開いたページが英語だとすぐ閉じちゃうらしいですけど。
そうでなくても英語よりも日本語のほうが読みやすいのは確かですね。
そんなこともあって、私もよくOSSのドキュメントを翻訳しています。
誰かがOSSドキュメントを翻訳すれば、より多くの人がそのOSSを使えるようになります。
(クリック)
もし、より多くの翻訳者が翻訳作業に参加できれば、より速く正確な翻訳ドキュメントを提供できます。
このセッションでは、翻訳に簡単に参加しやすい仕組みをどうやって作るのかを紹介します。
そのメカニズムを作るために、このセッションでは以下に紹介するツールを使います。
Tools; sphinx, docutils, sphinx-intl, transifex-client
Services; Transifex, Drone.io.
それでは、始めましょう。
まずはSphinxの紹介と、Sphinxの多言語対応向けセットアップからです。
Sphinx is 何?
Sphinxはドキュメンテーションジェネレータです。
SphinxはreStructuredTextというテキストマークアップから、複数の出力フォーマットに変換します。
(ポインタでinputとoutputを指す)
Sphinxの歴史をちょっとだけ紹介します。
この人がSphinxの父、Georg Brandlさんです。
PyCon JP 2013のキーノートスピーカーでした。
(クリック)
2007年まで、Pythonの公式ドキュメントはLaTeXで書かれていました。
しかし、これはメンテナンスが難しくて、ほぼ不可能。
Georgはこの状況を変えようとしました。
(クリック)
そして、2007年にSphinxを作りました。
Sphinxは書きやすくてメンテナンスしやすいことを目標に作られました。
Sphinx以前、以降
以前
Python界にはドキュメントを書く標準的な作法が確立していなかった。Python公式ドキュメントもそのうちのひとつで、ドキュメントはLaTeXでかかれていて、LaTeXに変換したりLaTeXから変換する多くのスクリプトジャングルがありました。その頃は、出力フォーマット別に、それらのジャングルスクリプトでマークアップを変換して、さらに別のツールで出力していました。
Sphinxがこの地に降りたって以降、* Python界の住人は、1つのソースコードから複数のフォーマットに出力できるようになりました。
* また、同梱されたHTMLテーマによって、ドキュメントは読みやすくなりました。
* APIリファレンスはライブラリの説明的ドキュメントと1つに統合して出力できるようになりました
* ReadTheDocsという自動ドキュメントビルド&ホスティングサービスが登場し、便利になりました
今では、Sphinxは多くのPythonライブラリで使われるドキュメンテーションツールになりました。
Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …
そしてPython以外のlibrary/toolsでもSphinxは使われています: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
今では、Sphinxは多くのPythonライブラリで使われるドキュメンテーションツールになりました。
Python libraries/tools: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …
そしてPython以外のlibrary/toolsでもSphinxは使われています: Chef, CakePHP(2.x), MathJax, Selenium, Varnish
Sphinxはdocutilsというライブラリをベースに作られています。
Sphinxはdocutilsにはない、多言語化の機能を提供しています。
のちほど、この多言語化機能を詳しく紹介します。
Sphinxと i18nツールのインストール
まず、Sphinxは当然インストールする必要がありますね。そして、 sphinx-intl と transifex-client を翻訳サポートのためにインストールします。
ところで、最新のtransifex-clientはちょっと安定してないため、私は0.8を使用しています。
まず、翻訳の対象となるソースコードを手に入れるところからです。
今回の例では、そのソースコードはSphinxで書かれたドキュメントをもう持っていることにします。
ですので、取ってきたソースコードのdocディレクトリで "make html"を実行すればHTMLが生成されるはずです。
出力は _build/html にあります。
ここで、ディレクトリ構成をみてみましょう。このようになっています。
(ポインタ)
* まず対象のソースコードはどこか既存のリポジトリからcloneしてきたものです
* ドキュメントのビルド出力 _build は "make html" で生成されたものです
* Sphinxで書かれたドキュメントソースの雛形は一般的に"sphinx-quickstart"コマンドで作られます
(クリック)
docディレクトリの中に、 conf.py ファイルがあります。
このファイルに2行追加してください。
* 3行目: 出力するドキュメントの言語コードです。
* 4行目: localeディレクトリへの相対パスです。このlocaleディレクトリには翻訳カタログファイルを置くことになります。
セットアップはこれでおわりです。
ここから主題に入っていきます。
Sphinxを使った貢献しやすいドキュメント翻訳プロセス、ってなんだろう、というのを見ていきます。
多言語化、ってなんでしょう。よく省略してI18Nと呼ばれます。
多言語化プロセスは、よく翻訳とか、ローカライズとかよばれますが、技術的には、こういった翻訳などを元のソースコードを書き直さずに行う事を多言語化といいます。
元のソースコードを書き直さずに行う、というのが重要なところです。
貢献しやすいってなに?
ソフトウエアの利用者やドキュメント読者は、たまに翻訳で協力したいと思うことがあります。
でも、翻訳に参加するのに準備が大変だったり、環境構築スキルが要求されたりすると、うわーっ!ってなってあきらめます。
「貢献しやすい」というのは、翻訳などで簡単に協力できる「状況」のことです。
3つのケース
HTMLだけで提供、翻訳できるけど、たいへん、元がちょくちょく更新される場合、どうやって追従する?
So, for the comparison, I'll introduce the three cases of difficult to contribute.
First one.
The manual are provided only in the HTML files.
Of course, you can translate it.
But, usually the html files are frequently updated.
How do you follow the original changes to update your translations?
This is the first case. I have no idea how to follow the original changes.
2つめ。ソースを書き換える。
reSTを壊さないように
多人数に作業を分割できない
元が更新されたらどうする?
2nd example.
When the manual are generated from reST files and docstrings in the source files,
You can rewrite original files to translate it.
But this approach has three problems:No1. You must be careful to maintain reStructuredText structure.No2. It's hard to divide translation tasks for a number of volunteer translators.No3. It's hard to pursue the upstream document source that is frequently updated.
last example.
OK, we are engineers. We can use git!
(上を読む)
Additionally, in this case, the repository owner should allow write access permission for each translators.
This is also not a easy way.
Well then, what is a easy way?
My opinion is this.Left side is Not a easy way.
Right side is A easy way.
We need a easy way.
The combination of the Sphinx i18n feature and some of the services can realize such a mechanism.
Sphinxのi18n機能と、いくつかのサービスを組み合わせてこの仕組みを実現します。
That's what is the goal of this session
これがゴール
I'll explain what how to create the mechanism in this session.
どうやって作るか説明します。
OK, let's move forward.
3rd Subject. Sphinx i18n feature.
I'll explain the detail of the feature.
Sphinx i18n は2つの機能で構成されてます。
1つめ。Potを生成
First one is the generation pot files from reST files.
pot file is a famous translation catalog format for gettext that is used for i18n, you know.
Potはi18n界では有名なgettext形式のカタログです
2つめ。reSTと、翻訳したPoから、翻訳HTMLを生成します
Second one is the generation translated html files with using po files that is translated version of catalogs.
It's the human work to prepare the translated po files from the pot files.
このpoを用意するのは人間の仕事です。
Like this, Converting the POT files into PO files is the job of humans.
(クリック)作者がpotを生成して、翻訳者に依頼します
(クリック)翻訳者はpotを受け取って、翻訳します。翻訳済みのファイルは拡張子をpoにします。
(クリック)おわったら、翻訳者は作者にpoを送ります
最初の部分をもうちょっと見ましょう
著者は "make gettext" でpotを生成します
"make gettext" はreSTのtextから文章を取りだしてpotに書き出します。もしSphinxのautodoc機能を使っていれば、Pythonソースからもドキュメントを読み込みます
このpotを翻訳すれば良いので、元のreSTやPythonコードを書き換える必要はありません。
"msgid" line have a original sentence.
"msgstr" line will have translated one.
このように翻訳カタログは1つの言語から別の言語に翻訳するのに便利です。
Translated PO files should have as a right side structure.
"locale" directory has "ja" and it has "LC_MESSAGES" directory, and it has translated PO files.
PO files are copies of POT files with changed file's extension.
If you want to translate it into other languages, like 'zh_cn', you can create other directories under "locale" directory.
When original POT files are updated by changing of original document, you should update PO files too.
If you had done it manually, it is very hard.
You can automated it by sphinx-intl.
At first, sphinx-intl copy pot files and rename them.
When the document is changed, translators can use sphinx-intl to update PO differences.
By same command.
As you see, translators can finish the boring tasks by one command.
sphinx-intl copy pot files and rename them on behalf of you.
sphinx-intl also update differences for each po files when the document is changed.
It's easy to use.
As a consequence of introducing the sphinx-intl tool, translators can concentrate for translation.
This is a translation work.
Translators can use their favorite editors or helpful tools/services easily that provide translation support features like a translation memory, recommending similar translation, glossary and auto-translation.
Once the translation is complete, finally let's run the "make html" command.
Finally author and translators can run "make html" and can get translated output w/o editing reST and python code.
This is a translated HTML sample.
Internally, Sphinx parse reST file and replace them into translated one by using po file.
Entire process to translate sphinx docs is this.
If you translate some sphinx document without using the i18n feature, you need to rewrite original document source files.
The Sphinx i18n feature provides a easy way to translate a document as you seen.
So far, we've found the mechanism of i18n of Sphinx.
In 4th Subject, Automated translation process with several services, we will continue to automate this mechanism.
Right now, we have seen an overall picture of the process.
Actually, I have a thing that was not pictured here.
(クリック)
Yes, these commands such as "make blah blah" require your hands to invoke.
In other words, the translator must learn such steps, yet.
Additionally, it would be difficult to translate in parallel.
It's not a easy way, you know.
OK, Let's make it to be automation and parallelization.
And then, the translator doesn't need to know the mechanism.
And, make the translation work possible to parallelize.
Let's take a look at from the parallelization of the translation work.
Once you get po files, you can use helpful tools/services easily that provide translation support features like a translation memory, recommending similar translation, glossary and auto-translation.
In particular, the use of the online translation service is important for parallelization.
I'd like to introduce the Transifex as a online translation service.
Transifex provides the following functions: Upload pot and download po files by API, glossary feature, translation memory, recommending translations, automatic translation by using Google / Microsoft API.
Because you can do translation on the Web screen, you can translate them with other translators in parallel.
Translation on Transifex web console.
1. You can select one untranslated message
2. And Translate it by your self, or by machine translation
3. If the message contains long module or method name, you can click the icon to copy original to translation box w/o typing.
4. Sometimes, you are suggested translation messages from other translator, or Translation Memory. Translation Memory (called TM) pick up suggestions from similar translation in the project or its historical changes. For example, When Doc Author fix a typo, translation will be discarded. However, TM suggests previous translation that matches 99% with current original message.
5. Once you finish the translation, you can save it.
6. Optionally, reviewer can review it.
We have made translation parallelization.
Next.
Let's automate the central part.
The procedure you want to automate is made up of 6 steps.
At first, we will review the 6 steps.
First step is, Clone repository to be translated.
Step 2. make gettext to generate translation catalog.
Step 3. Upload pot translation catalog source.
Step 4. Download translated po files.
Step 5. "make html" command to generate translated doc.
Step 6. Upload html to publish it
That's all.
Next, we will replace these all steps on the command line.
This is the command line that include the steps.
Line1: install sphinx and relates tools
Line2: clone repository
Line4: create a transifex account file by using sphinx-intl that reference environment variables (USERNAME and PASSWORD).
Line5: create a transifex config file by using sphinx-intl that also reference a environment variable (PROJECT_NAME)
Line6: generate pot files by make gettext
Line7: update resources information in transifex config file that also reference a environment variable (POT_DIR)
Line8: push pot files to transifex
Line9: pull translated po files from transifex
Line10: make html to generate translated html with using translated catalogs.
Now we replaced 5 steps on the command line, except HTML uploading part.
I'll explain the part later.
As you seen above, You can automate the process by this script.
Rest of work is preparing a environment to run the script automatically.
As one of the environment, I'll introduce the drone.io service.
The drone.io is a continuous integration service.
Drone integrates seamlessly with Github, Bitbucket and Google Code to make setup fast and simple.
Drone also integrates with Amazon, Heroku, Google AppEngine and more. For custom deployments you can use SSH and shell scripts.
You can use the service for public project without charge.
In my case, I usually use Github and S3 integrations.
Process of that is,
(クリック)
1. Push notification from GitHub
2. That invoke the script you've seen
3. Then, deploy html files onto S3 storage. (You need a publish html setting of S3)
If you set WebHook notification URL to transifex hook setting, updating translations also invoke the drone.io script.
By using drone.io service, automation can be achieved.
Upper-Left process is replaced with Right-Down one.
1 WebHook invoke the script.
The script execute commands 2, 3, 4, 5.
Finally drone.io deployment feature will deploy HTML to AWS S3 storage.
As this, we got the automated mechanism by using drone.io environment.
In summary, let's look at the results of the automation at each point of view as author and translators.
At first, a point of view from the doc author.
When author push to the repository, translation source of Transifex will be updated, and author can check the translated html in the site.
Doc Author doesn't require annoying procedure.
The second is, a point of view from doc translators.
They can translate the document in parallel with;
No git, No file, No conflict.
Translation source are updated Automatically
They can get a translated HTML output w/o hand-build.
It means that the translation contributors can focus on the translation.
By the mechanism of automation, both of doc author and translators will provide the maximum effect with a minimum of effort.
In order to make the mechanism, we'll use such tools and services in this session.
Tools; sphinx, docutils, sphinx-intl, transifex-client
Services; Transifex, Drone.io.
I'd like to introduce some of the tips.
Drone.io limits 15mins for a build.
If your process takes more than 15 minutes, you may be able to reduce the installation time with using wheel.
Wheel package is a installation format.
Installation speed is much faster than install from source distribution.
If you interested in it, please refer to https://bitbucket.org/sphinxjp/docutils-translation/
Version of transifex-client.
Looks like transifex-client 0.11b3 is not stable, for me.
Especially for Windows users.
If you have encountered trouble with using newer version, please try:
$ pip install "transifex-client=0.8"
This is a New project page of Drone.io.
Drone.io only list-up repositories which you have admin permission.
Because drone.io setup webhook, admin permission is required.
However, if you prepare a empty repository for drone.io usage, you can create a drone.io project.
It means you can prepare the i18n automation environment, except webhook push from github.
I think, project owner might be setup the webhook url for translation work, if you ask it.
It's bit a hacky way. But works.
These 3 examples are using earlier techniques.