Sphinx が支える翻訳ドキュメント

Sphinx が Python ドキュメントおよびその日本語訳をどう支えているかについて

Transcript

1. Sphinxが支える 翻訳ドキュメント 2017.11.28 @cocoatomo
2. アジェンダ お前誰よ 想定読者 Pythonドキュメントとは 翻訳プロジェクトの始め方 翻訳ドキュメントができるまで おまけ 結び
3. お前誰よ Pythonドキュメント日本語訳プロジェクト管理者 https://github.com/python-doc-ja 原文の更新が主な役割 たまにバグを見付けて, bugs.python.orgやSphinx プロジェクトに報告 最近のOSS活動では開発よりも翻訳で手を動かしている 最近の翻訳: pipenv http://pipenv- ja.readthedocs.io/ja/translate-ja/
4. 想定読者 主にSphinxを使っている方や翻訳プロジェクトの管 理に興味がある方 (超ニッチ!!) 翻訳プロジェクトの事例紹介 翻訳プロジェクトでSphinxをどう使うのか 翻訳プロジェクトの管理をどう楽にするのか それ以外の方には「翻訳ドキュメントが作られるまで に色んなことが起きている」ということを伝えたい
5. Pythonドキュメントとは (1/3) プログラミング言語Pythonの公式ドキュメント https://docs.python.org/3/ 言語仕様から標準ライブラリ, チュートリアル, FAQ, C APIなど内容が膨大 原稿の.rstファイル: 406個, 233,904行, 1,164,738ワー ド. 本にして1,596ページ, 5.8kg (2017/11/27) ref. https://www.wolframalpha.com/input/? i=1164738+words その上, 常にアップデートされている
6. Pythonドキュメントとは (2/3) 日本語やフランス語など複数言語に翻訳されている 2017/11/27時点の翻訳率 日本語 92.73% フランス語 22.72% ポルトガル語 (ブラジル) 19.2% 他の言語の翻訳作業も行われているけど, 翻訳率は低 め ref. https://www.transifex.com/python-doc/ python-36/languages/
7. Pythonドキュメントとは (3/3) 最近の大きなニュース PEP 545 -- Python Documentation Translations Python公式サイトで翻訳ドキュメントをホストする提案 ref. https://www.python.org/dev/peps/pep-0545/ ref. http://dsas.blog.klab.org/archives/2017-05/ python-dev-201705.html ref. http://dsas.blog.klab.org/archives/2017-05/ python-dev-201705.html 日本語版とフランス語版がdocs.python.orgドメインで公開さ れている
8. 翻訳ドキュメントが できるまで いったいどんなことが行われているのか? ???
9. 翻訳プロジェクトの始め方 翻訳プロジェクトを始めるにあたり考えること 原文と訳文は1対1か? 脚注, 訳注の追加や文章の 順序の入れ替えをしたいか? →1対1でないならSphinxを使うのを諦める 翻訳作業は1回きりなのか継続的に行うのか? 翻訳プロジェクトを管理する上で困難な点は何か? 困難な点をフォローするために, どのツールやサービ スを使って, どんな運用をしていくのか?
10. 2種類の翻訳作業 単発型 ある時点での固定化された原文に対しての翻訳作業. 基本 的に翻訳は一度きり. 例: 記事, 書籍の翻訳など. 継続型 時間の経過とともに変化する原文に追随していく翻訳作業. 訳文は随時更新されていく. 例: ライブラリのドキュメントの 翻訳など. ⇒単発型よりも継続型の方が管理が面倒. 単発型では, 原文 のコメントアウトand訳文の直書きで済ませてもよい. 以降の解説では主に継続型を主眼に置く.
11. 翻訳作業の困難さ 原文の管理 (必要なら) 更新の取り込み 訳文の管理 原文と訳文の対応付け 複数人作業による翻訳作業の衝突回避 翻訳 訳語の統一 表現の統一 (特に複数人作業)
12. 翻訳作業を支える 機能・サービス Version Control System (Git) → 原文と訳文の更新を記録 カタログ作成ツール (Sphinx gettext) → 翻訳対象の抽出および 原文と訳文の対応を管理 翻訳支援サービス (Transifex) 統合翻訳環境 → 翻訳作業に必要な機能を画面に配備 用語集 → 訳語の統一 原文が似ている訳文の提案 (翻訳メモリ) → 表現の統一 TransifexのCLIツール (transifex-client, sphinx-intl) 翻訳適用ツール (Sphinx i18n)
13. 翻訳ドキュメントができるまで Transifex fork Sphinx gettext transifex- client transifex- client 翻訳 sphinx- intl Sphinx i18n
14. 翻訳ドキュメントが できるまで ゴチャゴチャしてたので工程を1つずつ説明 処理フローの設計観点も含めつつ
15. fork (GitHub) 文字通り, 原文のファイル一式を翻訳プロジェクト用にforkする. [設計観点] 原文のブランチに追従する翻訳ブランチをどうするか? 案1: 原文と同名ブランチ (基本的にファイルを一切いじらない) Sphinx i18nで原文ファイルとカタログファイルを分離して管理 翻訳対象でない部分の翻訳は諦める 案2: 翻訳用ブランチ (必要であれば原文のファイルもいじる) 独自の仕組みを導入しやすい 例: Pythonドキュメントの「原文」リンク 独自の仕組みの部分が原文と乖離しやすく, 追従がツラい
16. Sphinx gettext Sphinxのgettextビルダーで原文のファイルから翻訳 対象を抽出し, カタログのテンプレートファイル (.pot ファイル) を作成する. 翻訳対象とするかどうかはSphinxが決めている. [設計観点] 翻訳対象とされていない対象も翻訳した くなったらどうするか? 案1: (前出の) 翻訳用ブランチ運用にして直接修 正 ※ただし更新が頻繁だとツラい 案2: SphinxプロジェクトにPull Requestを送る
17. transifex-client & sphinx-intl Sphinx gettextで作成したカタログのテンプレート ファイルをtransifex-clientでTransifexにアップ ロードする. sphinx-intlでtransifex-clientの設定ファイル を生成して, .potファイルおよび.poファイル (後 述) とTransifex上のリソース名の関連付けを行 う. [設計観点] (特に無し)
18. 翻訳 アップロードされた.potファイルを元に, Transifexが翻訳作業画面に 原文と訳文を記入するテキストボックスを表示してくれる. 翻訳率表示, 用語集の参照・登録, 原文と訳文の齟齬のチェック (URL, 数字など) も行ってくれる. ただし, その機能がただのうるさいお節介になることもある. [設計観点] どの翻訳支援サービスを使うか? .pot, .poファイルに対応していることが前提. Transifex以外にはZanata, pootle等がある. エディタの使いやすさ, 自動化に向いたCLIツールの有無などから 総合的に判断する.
19. Transifexの画面 実際のPython 3.6の翻訳作業画面
20. (再び) transifex-client Transifexが翻訳結果から作成したカタログファイ ル (.poファイル) をダウンロードする. .potファイルは.poファイルのテンプレート .potファイルに翻訳結果や翻訳言語, 翻訳日時 などのメタ情報を埋めたものが.poファイル [設計観点] (特に無し)
21. Sphinx i18n 原文 (正確には原文のdoctree) に翻訳を適用す る. 各フォーマットへの変換の部分は各ビルダーが行 う. doctreeはreSTファイルの内容を木構造に変換 し, 各節点にドキュメントの情報を持たせたもの. [設計観点] (特に無し)
22. おまけ 翻訳プロジェクトをやっていてよかったこと 英語と英語の日本語訳作業に慣れる Pythonに貢献できる (Misc/ACKSに名前が載る) Sphinxに貢献できる (ツールを改善する経験) 継続的デリバリー (CI) の経験が積める Python界隈での便利な名刺になる
23. 結びとして PythonドキュメントはSphinxで成り立っている. 況んや日本語訳プロジェクトをや! Sphinxの機能がユーザー側の要望で改善されていく のは, どちら側にとってもメリットになる. 今後とも変わらぬお付き合いを是非ともよろしくお願 いいたします!!! (to Sphinx Committers) ...
24. 真の結びとして 意訳: これからもたくさん質問・ 相談投げるのでヨロシク!!
 (to Sphinx Committers)