Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

22,572 views

Published on

Sphinxには、多言語化サポート機能があります。 この機能を使用せずにSphinxで書かれたドキュメントを翻訳するには、ドキュメントのソースを書き換えることになります。 しかし、この方法には3つの問題があります。

Sphinxの文章フォーマットを壊さないように気をつけなければならない
多数のボランティアによる翻訳の分担がしづらい、ボランティア参加しづらい
オリジナルドキュメントが更新されたとき、翻訳ドキュメントを追従させるのが難しい
そこで、Sphixnの多言語化サポート機能を利用します。 Sphinxはgettext形式の翻訳カタログの入出力に対応しているので、翻訳支援機能を備えたさまざまなツールやサービスを簡単に利用できます。 翻訳支援サービスを使うことで、Sphinxのドキュメント翻訳は以下のように実施出来ます。

パラグラフ単位で翻訳できる(Sphinxがパラグラフ単位で翻訳カタログに出力します)
多人数で同時編集できる
翻訳メモリや自動翻訳などの機能を使える
このようなサービスを利用すると、ボランティアが翻訳に参加しやすくなります。 Sphinx-users.jpチームは、Sphinxとtransifexというサービスを組み合わせて、ドキュメント翻訳の仕組みを作りました。 さらに、drone.ioを使ってプロセス全体を自動化しています。 これによって、(A)元のドキュメントが更新されたときに、transifexの翻訳元文章が更新されます。(B)transifexで翻訳が行われると、その翻訳を取り込んだドキュメントが自動ビルドされてホスティングサーバーにデプロイされます。

このセッションでは、プロセスの全体像と、自動化の仕組みについて紹介し、Sphinxで書かれたドキュメントを翻訳するうえでのヒント、コツ、そして注意点についてお話しします。

Published in: Technology
  • Be the first to comment

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

  1. 1. 1 Takayuki Shimizukawa Sphinx co-maintainer Sphinx-users.jp
  2. 2. Ahoj, 안녕하세요, Hola, Hello, こんにちは 2
  3. 3. おまえ誰よ @shimizukawa 1. Sphinx メンテナ 2. Sphinx-users.jp 3. 一般社団法人PyCon JP 理事  BePROUD co, ltd. 3
  4. 4. 今年はスタッフじゃ無いのに間違えられる 4
  5. 5. 今日の予定 1. Sphinx紹介 & i18nセットアップ 2. 貢献しやすいドキュメント翻訳 3. Sphinxのi18n機能 4. 翻訳プロセスの自動化と便利なサービス 5. Tips, tricks, traps 5
  6. 6. 6
  7. 7. 質問1 オープンソースソフトウエア を使っている方 7
  8. 8. 質問2 OSSにコントリビュートし たことがある方 8
  9. 9. 質問3 ドキュメントを 日本語に翻訳することは 他の開発者の助けになる と思いますか? 9
  10. 10. ドキュメント翻訳の価値 10 翻訳者 プロダクト 作者 翻訳Docs 読者 英語Docs
  11. 11. ツール & サービス ツール 1. sphinx - ドキュメントジェネレータ 2. sphinx-intl - Sphinx i18n機能の補助ツール 3. transifex-client - Transifexサービスのファイルを送 受信するツール サービス 1. Transifex - 翻訳サポートサービス 2. Drone.io - 継続的インテグレーションサービス 11
  12. 12. 12
  13. 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. 14. Sphinxの歴史 (ショートver.) 14 1. Sphinx紹介 & i18nセットアップ Sphinxの 父 メンテナンス が大変 ~2007 書きやすく メンテナンスしやす い2007~
  15. 15. Sphinx 以前、Sphinx以降 Sphinx以前  ドキュメントを書く標準的な方法がなかった  出力フォーマットに合わせて、一度書いたドキュメント を変換する必要があった Sphinx以降  1つのソースから複数フォーマットのドキュメントを生 成  同梱のHTMLテーマ機能で読みやすいドキュメントを提 供  APIリファレンスと説明的ドキュメントが同居できる  自動ビルドとホスティングを提供するReadTheDocsの登 15 1. Sphinx紹介 & i18nセットアップ
  16. 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. 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. 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. 19. $ pip install sphinx 翻訳サポートツールをインストール Sphinxと i18nツールのインストール Sphinx本体をインストール $ pip install sphinx-intl $ pip install transifex-client=0.8 19 1. Sphinx紹介 & i18nセットアップ
  20. 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セットアップ
  21. 21. ファイルの一覧と & conf.pyの設定 $ tree /path/to/deepthought +- deep_thought | +- __init__.py | +- api.py | +- calc.py | +- utils.py +- doc | +- _build/ | | +- html/ | +- _static/ | +- _template/ | +- conf.py | +- index.py | +- make.bat | +- Makefile +- setup.py 21 1. Sphinx紹介 & i18nセットアップ ドキュメントソース Document build output Target library for doc1. ... 2. 3. language = 'ja' 4. locale_dirs = ['locale'] 5. doc/conf.py
  22. 22. 22
  23. 23. 多言語化 internationalization 23 2.貢献しやすいドキュメント翻訳 I18N
  24. 24. 貢献しやすいって どういう状況? 24 2.貢献しやすいドキュメント翻訳
  25. 25. 翻訳しにくい例 (1/3) マニュアルがHTMLファイルでのみ 提供されている HTMLファイルを書き換える? 25 2.貢献しやすいドキュメント翻訳
  26. 26. 翻訳しにくい例 (2/3) マニュアルがreSTファイルやソース コード内のdocstringから生成されてい る  reSTファイルを書き換える?  ソース内のdocstrinsを書き換える? 26 2.貢献しやすいドキュメント翻訳
  27. 27. 翻訳しにくい例 (3/3) 翻訳対象がgitで管理されている  gitを学ぶ  GitHubを学ぶ  "git clone" してソースコードを取得する  翻訳 (これ!これやりたかった!)  "git commit"  "git pull"  時々競合が発生して解決しないといけない  "git push" 27 2.貢献しやすいドキュメント翻訳
  28. 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. 29
  30. 30. 2つのi18n機能  pot ファイルの生成: reSTから  po ファイルの読み込み: 翻訳済みHTMLを生成するため 30 3. Sphinxのi18n機能 reST pot reST html po
  31. 31. 翻訳の流れ  potを生成  potをpoに翻訳  翻訳済みHTMLを生成 31 3. Sphinxのi18n機能 reST pot reST html po pot po Translator 翻訳して~ 翻訳した! 協力ありがとう!
  32. 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
  33. 33. 翻訳前にpoファイルを準備 doc +- _build/ | +- gettext/ | +- api.pot | +- examples.pot | +- generated.pot | +- index.pot +- locale/ doc +- _build/ +- locale/ +- ja/ | +- LC_MESSAGES/ | +- api.po | +- examples.po | +- generated.po | +- index.po +- zh_cn/ これらを翻訳 翻訳者 pot po 33 3. Sphinxのi18n機能
  34. 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. 35. po ファイルを翻訳 #: ../../../deep_thought/utils.py:docstring of deep_thought.utils.dumps:1 msgid "Serialize ``obj`` 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 ``obj`` to a JSON formatted :class:`str`." msgstr "``obj`` をJSONフォーマットした :class:`str` にシリアライズ。 " generated.po Vim, Emacs, OmegaT, ... 等を使って翻訳 35 3. Sphinxのi18n機能
  36. 36. po ファイルを読み込み 36 3. Sphinxのi18n機能 reST html po 翻訳済み $ make html ... Build finished. The HTML pages are in _build/html.
  37. 37. 全体の流れ 37 3. Sphinxのi18n機能 reST pot html po make gettext sphinx-intl 翻訳者 make html ドキュメント作者 翻訳カタログ 翻訳済み カタログ
  38. 38. 38
  39. 39. Sphinxドキュメント翻訳プロセス全体像 39 4.翻訳プロセスの自動化と便利なサービス reST pot html po make gettext sphinx-intl make html ドキュメント作者 翻訳カタログ 翻訳済カタログ 翻訳者 翻訳者 翻訳者 作者 / 翻訳者 アップロード 翻訳者 clone 翻訳者
  40. 40. 自動化したい2つの部分 40 4.翻訳プロセスの自動化と便利なサービス reST pot html po make gettext sphinx-intl make html ドキュメント作者 翻訳カタログ 翻訳済カタログ アップロード 翻訳者 自動化したい 並列化 したい clone
  41. 41. 翻訳ツールの種類  Vim / Emacs (エディタ)  ローカルファイルの編集  いくつかの翻訳サポートプラグイン  OmegaT (翻訳ツール)  ローカルファイルの編集  いくつかの翻訳サポート機能  Transifex (サービス)  オンライン編集  いくつかの翻訳サポート 機能 41 4.翻訳プロセスの自動化と便利なサービス po 翻訳者 並列化 したい
  42. 42. Transifexを用いた並列化 Transifexが提供する機能 APIとして: アップロード pot ダウンロード po Webコンソールとして: 用語集 翻訳メモリ レコメンド 機械翻訳 42 4.翻訳プロセスの自動化と便利なサービス po 翻訳者 並列化 pot アップロード pot 自動反映 sphinx-intl transifex-client po transifex-client ダウンロード
  43. 43. Transifex Webコンソールで翻訳 43 4.翻訳プロセスの自動化と便利なサービス 原文 翻訳文(reST文法を 壊さないように!) 翻訳メモリ (TM) からの レコメンド 原文 (pot) 翻訳 (po) 原文を翻訳文にコピー 機械翻訳 保存 レビュー (必要なら) 翻訳者 並列化 1 2 4 3 5 6
  44. 44. 自動化したい2つの部分 44 4.翻訳プロセスの自動化と便利なサービス po 翻訳者 並列化 pot アップロード pot 自動更新 sphinx-intl transifex-client po transifex-client ダウンロード reST html make gettext make html ドキュメント作者 アップロード 自動化したい clone
  45. 45. 全体の処理を自動化したい 45 4.翻訳プロセスの自動化と便利なサービス pot アップロード sphinx-intl transifex-client po transifex-client ダウンロード reST html make gettext make htmlアップロード clone 1 2 3 45 6 自動化したい
  46. 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. 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. 48. drone.ioによる自動化 48 WebHook デプロイ リポジトリClone シェルスクリプト実行 drone.io は継続的インテグレーションサービス 4.翻訳プロセスの自動化と便利なサービス
  49. 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. 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. 51. Drone.ioによる自動化 51 アップロード pot ダウンロード po アップロード html WebHook clone 1 5 6 make html make gettext2 3 4 1 WebHook 自動化 4.翻訳プロセスの自動化と便利なサービス
  52. 52. ドキュメント作者の視点  ドキュメント作者は、面倒な手間をかけずに、翻訳原文 の更新やサイトの閲覧ができる 翻訳原文の更新 ドキュメント作者 通知 閲覧 Commit 52 4.翻訳プロセスの自動化と便利なサービス
  53. 53. 翻訳者の視点  No git  No file  No conflict  自動的に更新  手動ビルドせずに翻訳されたHTMLを閲覧できる 翻訳者 並列化 閲覧 翻訳 翻訳されたHTML 53 4.翻訳プロセスの自動化と便利なサービス
  54. 54. 自動化された全プロセス 54 アップデート 翻訳カタログ ドキュメント作者 翻訳者 並列化 通知 閲覧 閲覧 更新 翻訳 Commit ダウンロード Translations 通知 Automated 4.翻訳プロセスの自動化と便利なサービス
  55. 55. まとめ ツール 1. sphinx - ドキュメントジェネレータ 2. sphinx-intl - Sphinx i18n機能の補助ツール 3. transifex-client - Transifexサービスのファイルを送 受信するツール サービス 1. Transifex - 翻訳サポートサービス 2. Drone.io - 継続的インテグレーションサービス 55 4.翻訳プロセスの自動化と便利なサービス
  56. 56. 56
  57. 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. 58. TRAP: transifex-clientのバージョン  transifex-client 0.11b3は安定してない(と思 う)  特にWindowsユーザーにとって  もし最新版でうまくいかない場合は、以下 のようにバージョン指定してみてください: 58 5. Tips, tricks, traps $ pip install "transifex-client=0.8"
  59. 59.  Drone.io はGithubか Bitbucketの管理権限の あるリポジトリ用のプ ロジェクトしか作れな い  Github等に空リポジト リを用意してDrone.ioプ ロジェクトを作成し、 そのWebHook URLを対 象リポジトリの管理者 に設定してもらおう 59 TRICK: Drone.io プロジェクトの用意 5. Tips, tricks, traps
  60. 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. 61. Questions? @shimizukawa いつでもつかまえてね :) OpenSpace, Party, Poster, Sprint 61
  62. 62. Thanks :) 62

×