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