Sphinxで作る貢献しやすいドキュメント翻訳の仕組み

1. 1 Takayuki Shimizukawa Sphinx co-maintainer Sphinx-users.jp

2. Ahoj, 안녕하세요, Hola, Hello, こんにちは 2

3. おまえ誰よ @shimizukawa 1. Sphinx メンテナ 2. Sphinx-users.jp 3. 一般社団法人PyCon JP 理事  BePROUD co, ltd. 3

4. 今年はスタッフじゃ無いのに間違えられる 4

5. 今日の予定 1. Sphinx紹介 & i18nセットアップ 2. 貢献しやすいドキュメント翻訳 3. Sphinxのi18n機能 4. 翻訳プロセスの自動化と便利なサービス 5. Tips, tricks, traps 5

7. 質問1 オープンソースソフトウエアを使っている方 7

8. 質問2 ＯＳＳにコントリビュートしたことがある方 8

9. 質問3 ドキュメントを日本語に翻訳することは他の開発者の助けになると思いますか？ 9

10. ドキュメント翻訳の価値 10 翻訳者プロダクト作者翻訳Docs 読者英語Docs

11. ツール & サービスツール 1. sphinx - ドキュメントジェネレータ 2. sphinx-intl - Ｓｐｈｉｎｘ i18n機能の補助ツール 3. transifex-client - Transifexサービスのファイルを送受信するツールサービス 1. Transifex - 翻訳サポートサービス 2. Drone.io - 継続的インテグレーションサービス 11

12. 12

13. Sphinx is 何? Sphinx はドキュメンテーションジェネレータです SphinxはreSTマークアップから複数のフォーマットのドキュメントを生成します 13 1. Sphinx紹介 & i18nセットアップ Sphinx reSTreSTreStructuredText (reST) reST Parser HTML Builder ePub Builder LaTeX Builder texlive HTML theme Favorite Editor

14. Sphinxの歴史 (ショートver.) 14 1. Sphinx紹介 & i18nセットアップＳｐｈｉｎｘの父メンテナンスが大変 ~2007 書きやすくメンテナンスしやすい2007~

15. Sphinx 以前、Sphinx以降 Sphinx以前  ドキュメントを書く標準的な方法がなかった  出力フォーマットに合わせて、一度書いたドキュメントを変換する必要があった Sphinx以降  １つのソースから複数フォーマットのドキュメントを生成  同梱のHTMLテーマ機能で読みやすいドキュメントを提供  APIリファレンスと説明的ドキュメントが同居できる  自動ビルドとホスティングを提供するReadTheDocsの登 15 1. Sphinx紹介 & i18nセットアップ

16. Sphinxで書かれたドキュメントの例  Python ライブラリ/ツール: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …  Python以外のライブラリ/ツール: Chef, CakePHP(2.x), MathJax, Selenium, Varnish 16 1. Sphinx紹介 & i18nセットアップ

17. Sphinxで書かれたドキュメントの例  Python ライブラリ/ツール: Python, Sphinx, Flask, Jinja2, Django, Pyramid, SQLAlchemy, Numpy, SciPy, scikit-learn, pandas, fabric, ansible, awscli, …  Python以外のライブラリ/ツール: Chef, CakePHP(2.x), MathJax, Selenium, Varnish 17 1. Sphinx紹介 & i18nセットアップ

18. SPHINX docutils HTML Builder HTML theme (Jinja2) gettext Builder *.pot *.po I18N *.mo OmegaT Pootle Transifex Translation Tools, Services Favorite Editor Sphinxのi18n機能 (ビルトイン) 18 1. Sphinx紹介 & i18nセットアップ reST Parser (directive / role) doctree (Intermediate) reSTreST reStructuredText (reST)

19. $ pip install sphinx 翻訳サポートツールをインストール Sphinxと i18nツールのインストール Sphinx本体をインストール $ pip install sphinx-intl $ pip install transifex-client=0.8 19 1. Sphinx紹介 & i18nセットアップ

20. $ git clone https://github.com/shimizukawa/deepthought.git $ cd deepthought/doc $ make html ... Build finished. The HTML pages are in _build/html. "make html" コマンドで _build/html ディレクトリ以下にhtmlファイルが生成されます最初のmake html 20 1. Sphinx紹介 & i18nセットアップ

22. 22

23. 多言語化 internationalization 23 2.貢献しやすいドキュメント翻訳 I18N

24. 貢献しやすいってどういう状況？ 24 2.貢献しやすいドキュメント翻訳

25. 翻訳しにくい例 (1/3) マニュアルがHTMLファイルでのみ提供されている HTMLファイルを書き換える? 25 2.貢献しやすいドキュメント翻訳

26. 翻訳しにくい例 (2/3) マニュアルがreSTファイルやソースコード内のdocstringから生成されている  reSTファイルを書き換える?  ソース内のdocstrinsを書き換える? 26 2.貢献しやすいドキュメント翻訳

27. 翻訳しにくい例 (3/3) 翻訳対象がgitで管理されている  gitを学ぶ  GitHubを学ぶ  "git clone" してソースコードを取得する  翻訳 (これ！これやりたかった！)  "git commit"  "git pull"  時々競合が発生して解決しないといけない  "git push" 27 2.貢献しやすいドキュメント翻訳

28. めんどう vs かんたんめんどうかんたん 1. gitを学ぶ 2. GitHubを学ぶ 3. "git clone" 4. 翻訳 5. "git commit" / "git push" 6. "git pull" 7. 時々競合解決 8. HTMLを自分でビルド 1. git 使わない 2. Github 使わない 3. file 触らない 4. 翻訳 5. 翻訳は自動更新 6. 競合しない 7. 自分でビルドしなくてもHTMLをゲット 28 2.貢献しやすいドキュメント翻訳

29. 29

30. 2つのi18n機能  pot ファイルの生成: reSTから  po ファイルの読み込み: 翻訳済みHTMLを生成するため 30 3. Sphinxのi18n機能 reST pot reST html po

31. 翻訳の流れ  potを生成  potをpoに翻訳  翻訳済みHTMLを生成 31 3. Sphinxのi18n機能 reST pot reST html po pot po Translator 翻訳して～翻訳した！協力ありがとう！

32. #: ../../../deep_thought/utils.py:docstring of deep_thought.utils.dumps:1 msgid "Serialize ``obj`` to a JSON formatted :class:`str`." msgstr "" msgid "For example:" msgstr "" 32 pot ファイル生成 3. Sphinxのi18n機能 $ make gettext ... Build finished. The message catalogs are in _build/gettext. $ ls _build/gettext api.pot examples.pot generated.pot index.pot generated.pot reST pot

34. 34 翻訳前にpoファイルを準備 $ sphinx-intl update -p _build/gettext -l zh_cn Create: locale/zh_cn/LC_MESSAGES/api.po Create: locale/zh_cn/LC_MESSAGES/examples.po Create: locale/zh_cn/LC_MESSAGES/generated.po Create: locale/zh_cn/LC_MESSAGES/index.po sphinx-intl コマンドで「名前を変えてコピー」 pot po sphinx-intl $ make gettext $ sphinx-intl update -p _build/gettext -l zh_cn Not Changed: locale/zh_cn/LC_MESSAGES/api.po Updated: locale/zh_cn/LC_MESSAGES/examples.po +3, -1 ドキュメントが更新されたら、同じコマンドでpoを更新 3. Sphinxのi18n機能

35. po ファイルを翻訳 #: ../../../deep_thought/utils.py:docstring of deep_thought.utils.dumps:1 msgid "Serialize `òbj`` to a JSON formatted :class:`str`." msgstr "" generated.po pot po sphinx-intl 翻訳者 #: ../../../deep_thought/utils.py:docstring of deep_thought.utils.dumps:1 msgid "Serialize `òbj`` to a JSON formatted :class:`str`." msgstr "`òbj`` をJSONフォーマットした :class:`str` にシリアライズ。 " generated.po Vim, Emacs, OmegaT, ... 等を使って翻訳 35 3. Sphinxのi18n機能

36. po ファイルを読み込み 36 3. Sphinxのi18n機能 reST html po 翻訳済み $ make html ... Build finished. The HTML pages are in _build/html.

37. 全体の流れ 37 3. Sphinxのi18n機能 reST pot html po make gettext sphinx-intl 翻訳者 make html ドキュメント作者翻訳カタログ翻訳済みカタログ

38. 38

39. Sphinxドキュメント翻訳プロセス全体像 39 4.翻訳プロセスの自動化と便利なサービス reST pot html po make gettext sphinx-intl make html ドキュメント作者翻訳カタログ翻訳済カタログ翻訳者翻訳者翻訳者作者 / 翻訳者アップロード翻訳者 clone 翻訳者

40. 自動化したい2つの部分 40 4.翻訳プロセスの自動化と便利なサービス reST pot html po make gettext sphinx-intl make html ドキュメント作者翻訳カタログ翻訳済カタログアップロード翻訳者自動化したい並列化したい clone

41. 翻訳ツールの種類  Vim / Emacs (エディタ)  ローカルファイルの編集  いくつかの翻訳サポートプラグイン  OmegaT (翻訳ツール)  ローカルファイルの編集  いくつかの翻訳サポート機能  Transifex (サービス)  オンライン編集  いくつかの翻訳サポート機能 41 4.翻訳プロセスの自動化と便利なサービス po 翻訳者並列化したい

42. Transifexを用いた並列化 Transifexが提供する機能 APIとして: アップロード pot ダウンロード po Webコンソールとして: 用語集 翻訳メモリ レコメンド 機械翻訳 42 4.翻訳プロセスの自動化と便利なサービス po 翻訳者並列化 pot アップロード pot 自動反映 sphinx-intl transifex-client po transifex-client ダウンロード

43. Transifex Webコンソールで翻訳 43 4.翻訳プロセスの自動化と便利なサービス原文翻訳文(reST文法を壊さないように！) 翻訳メモリ (TM) からのレコメンド原文 (pot) 翻訳 (po) 原文を翻訳文にコピー機械翻訳保存レビュー (必要なら) 翻訳者並列化 1 2 4 3 5 6

44. 自動化したい2つの部分 44 4.翻訳プロセスの自動化と便利なサービス po 翻訳者並列化 pot アップロード pot 自動更新 sphinx-intl transifex-client po transifex-client ダウンロード reST html make gettext make html ドキュメント作者アップロード自動化したい clone

45. 全体の処理を自動化したい 45 4.翻訳プロセスの自動化と便利なサービス pot アップロード sphinx-intl transifex-client po transifex-client ダウンロード reST html make gettext make htmlアップロード clone 1 2 3 45 6 自動化したい

46. 自動化の手順 1. リポジトリをclone 2. "make gettext" 3. アップロード pot 4. ダウンロード po 5. "make html" 6. アップロード html 46 4.翻訳プロセスの自動化と便利なサービス pot アップロード sphinx-intl transifex-client po transifex-client ダウンロード reST html make gettext make html アップロード clone 1 2 3 45 6 自動化したい

47. 1. pip install sphinx sphinx-intl transifex-client==0.8 2. git clone https://github.com/shimizukawa/deepthought.git 3. cd deepthought/doc 4. sphinx-intl create-transifexrc # create ~/.transifexrc 5. sphinx-intl create-txconfig # create .tx/config 6. make gettext 7. sphinx-intl -p _build/gettext update-txconfig-resources # update .tx/config 8. tx push -s # push pot files to transifex 9. tx pull -l ja # pull po files from transifex 10. make html SPHINXOPTS="-D language=ja" 自動化のためのシェルコマンド run.sh $ export SPHINXINTL_TRANSIFEX_USERNAME=mice $ export SPHINXINTL_TRANSIFEX_PASSWORD=42 $ export SPHINXINTL_TRANSIFEX_PROJECT_NAME=deepthought-0_7 $ export SPHINXINTL_POT_DIR=_build/gettext $ run.sh 47 4.翻訳プロセスの自動化と便利なサービス

48. drone.ioによる自動化 48 WebHook デプロイリポジトリClone シェルスクリプト実行 drone.io は継続的インテグレーションサービス 4.翻訳プロセスの自動化と便利なサービス

49. GitHub + drone.io + S3 49 GitHub Amazon S3 Transifex 1. リポジトリClone 2. make gettext 3. アップロード pot 4. ダウンロード po 5. make html 6. アップロード html 4.翻訳プロセスの自動化と便利なサービス 2 1 3 1

50. Drone.ioによる自動化 50 pot アップロード sphinx-intl transifex-client po transifex-client Download reST html make gettext make html アップロード clone 1 2 3 45 6 To Be Automated アップロード pot ダウンロード po アップロード html WebHook clone 1 5 6 make html make gettext2 3 4 1 WebHook 自動化 4.翻訳プロセスの自動化と便利なサービス

51. Drone.ioによる自動化 51 アップロード pot ダウンロード po アップロード html WebHook clone 1 5 6 make html make gettext2 3 4 1 WebHook 自動化 4.翻訳プロセスの自動化と便利なサービス

52. ドキュメント作者の視点  ドキュメント作者は、面倒な手間をかけずに、翻訳原文の更新やサイトの閲覧ができる翻訳原文の更新ドキュメント作者通知閲覧 Commit 52 4.翻訳プロセスの自動化と便利なサービス

53. 翻訳者の視点  No git  No file  No conflict  自動的に更新  手動ビルドせずに翻訳されたHTMLを閲覧できる翻訳者並列化閲覧翻訳翻訳されたHTML 53 4.翻訳プロセスの自動化と便利なサービス

54. 自動化された全プロセス 54 アップデート翻訳カタログドキュメント作者翻訳者並列化通知閲覧閲覧更新翻訳 Commit ダウンロード Translations 通知 Automated 4.翻訳プロセスの自動化と便利なサービス

55. まとめツール 1. sphinx - ドキュメントジェネレータ 2. sphinx-intl - Ｓｐｈｉｎｘ i18n機能の補助ツール 3. transifex-client - Transifexサービスのファイルを送受信するツールサービス 1. Transifex - 翻訳サポートサービス 2. Drone.io - 継続的インテグレーションサービス 55 4.翻訳プロセスの自動化と便利なサービス

56. 56

57. TIP: Drone.io の15分制限  Drone.io はビルド1回の時間を15分に制限している  パッケージのインストールをwheelで行い時間短縮 57 5. Tips, tricks, traps 1. curl -L -s https://example.com/wheelhouse.tgz | tar vzxf - 2. export PIP_FIND_LINKS=./wheelhouse 3. pip install sphinx sphinx-intl transifex-client==0.8 run.sh ex. https://bitbucket.org/sphinxjp/docutils-translation/

58. TRAP: transifex-clientのバージョン  transifex-client 0.11b3は安定してない（と思う）  特にWindowsユーザーにとって  もし最新版でうまくいかない場合は、以下のようにバージョン指定してみてください: 58 5. Tips, tricks, traps $ pip install "transifex-client=0.8"

59.  Drone.io はGithubか Bitbucketの管理権限のあるリポジトリ用のプロジェクトしか作れない  Github等に空リポジトリを用意してDrone.ioプロジェクトを作成し、そのWebHook URLを対象リポジトリの管理者に設定してもらおう 59 TRICK: Drone.io プロジェクトの用意 5. Tips, tricks, traps

60. 利用事例  Sphinx-1.3 doc for "ja" translation https://drone.io/bitbucket.org/shimizukawa/sphinx-doc13/admin  Sphinx-1.4 doc for "ja" translation https://drone.io/bitbucket.org/shimizukawa/sphinx-doc14/admin  Docutils doc for "ja" translation https://drone.io/bitbucket.org/sphinxjp/docutils-translation/admin 60 5. Tips, tricks, traps

61. Questions? @shimizukawa いつでもつかまえてね :) OpenSpace, Party, Poster, Sprint 61

62. Thanks :) 62

Sphinxで作る貢献しやすい ドキュメント翻訳の仕組み

Takayuki Shimizukawa