$30 off During Our Annual Pro Sale. View Details »

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

cocoatomo
PRO
February 15, 2018

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

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

cocoatomo
PRO

February 15, 2018
Tweet

More Decks by cocoatomo

Other Decks in Programming

Transcript

  1. Sphinxが支える
    翻訳ドキュメント
    2017.11.28
    @cocoatomo

    View Slide

  2. アジェンダ
    お前誰よ
    想定読者
    Pythonドキュメントとは
    翻訳プロジェクトの始め方
    翻訳ドキュメントができるまで
    おまけ
    結び

    View Slide

  3. お前誰よ
    Pythonドキュメント日本語訳プロジェクト管理者
    https://github.com/python-doc-ja
    原文の更新が主な役割
    たまにバグを見付けて, bugs.python.orgやSphinx
    プロジェクトに報告
    最近のOSS活動では開発よりも翻訳で手を動かしている
    最近の翻訳: pipenv http://pipenv-
    ja.readthedocs.io/ja/translate-ja/

    View Slide

  4. 想定読者
    主にSphinxを使っている方や翻訳プロジェクトの管
    理に興味がある方 (超ニッチ!!)
    翻訳プロジェクトの事例紹介
    翻訳プロジェクトでSphinxをどう使うのか
    翻訳プロジェクトの管理をどう楽にするのか
    それ以外の方には「翻訳ドキュメントが作られるまで
    に色んなことが起きている」ということを伝えたい

    View Slide

  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
    その上, 常にアップデートされている

    View Slide

  6. Pythonドキュメントとは
    (2/3)
    日本語やフランス語など複数言語に翻訳されている
    2017/11/27時点の翻訳率
    日本語 92.73%
    フランス語 22.72%
    ポルトガル語 (ブラジル) 19.2%
    他の言語の翻訳作業も行われているけど, 翻訳率は低

    ref. https://www.transifex.com/python-doc/
    python-36/languages/

    View Slide

  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ドメインで公開さ
    れている

    View Slide

  8. 翻訳ドキュメントが
    できるまで
    いったいどんなことが行われているのか?
    ???

    View Slide

  9. 翻訳プロジェクトの始め方
    翻訳プロジェクトを始めるにあたり考えること
    原文と訳文は1対1か? 脚注, 訳注の追加や文章の
    順序の入れ替えをしたいか?
    →1対1でないならSphinxを使うのを諦める
    翻訳作業は1回きりなのか継続的に行うのか?
    翻訳プロジェクトを管理する上で困難な点は何か?
    困難な点をフォローするために, どのツールやサービ
    スを使って, どんな運用をしていくのか?

    View Slide

  10. 2種類の翻訳作業
    単発型
    ある時点での固定化された原文に対しての翻訳作業. 基本
    的に翻訳は一度きり. 例: 記事, 書籍の翻訳など.
    継続型
    時間の経過とともに変化する原文に追随していく翻訳作業.
    訳文は随時更新されていく. 例: ライブラリのドキュメントの
    翻訳など.
    ⇒単発型よりも継続型の方が管理が面倒. 単発型では, 原文
    のコメントアウトand訳文の直書きで済ませてもよい.
    以降の解説では主に継続型を主眼に置く.

    View Slide

  11. 翻訳作業の困難さ
    原文の管理
    (必要なら) 更新の取り込み
    訳文の管理
    原文と訳文の対応付け
    複数人作業による翻訳作業の衝突回避
    翻訳
    訳語の統一
    表現の統一 (特に複数人作業)

    View Slide

  12. 翻訳作業を支える
    機能・サービス
    Version Control System (Git) → 原文と訳文の更新を記録
    カタログ作成ツール (Sphinx gettext) → 翻訳対象の抽出および
    原文と訳文の対応を管理
    翻訳支援サービス (Transifex)
    統合翻訳環境 → 翻訳作業に必要な機能を画面に配備
    用語集 → 訳語の統一
    原文が似ている訳文の提案 (翻訳メモリ) → 表現の統一
    TransifexのCLIツール (transifex-client, sphinx-intl)
    翻訳適用ツール (Sphinx i18n)

    View Slide

  13. 翻訳ドキュメントができるまで
    Transifex
    fork
    Sphinx
    gettext
    transifex-
    client
    transifex-
    client
    翻訳
    sphinx-
    intl
    Sphinx
    i18n

    View Slide

  14. 翻訳ドキュメントが
    できるまで
    ゴチャゴチャしてたので工程を1つずつ説明
    処理フローの設計観点も含めつつ

    View Slide

  15. fork (GitHub)
    文字通り, 原文のファイル一式を翻訳プロジェクト用にforkする.
    [設計観点] 原文のブランチに追従する翻訳ブランチをどうするか?
    案1: 原文と同名ブランチ (基本的にファイルを一切いじらない)
    Sphinx i18nで原文ファイルとカタログファイルを分離して管理
    翻訳対象でない部分の翻訳は諦める
    案2: 翻訳用ブランチ (必要であれば原文のファイルもいじる)
    独自の仕組みを導入しやすい
    例: Pythonドキュメントの「原文」リンク
    独自の仕組みの部分が原文と乖離しやすく, 追従がツラい

    View Slide

  16. Sphinx gettext
    Sphinxのgettextビルダーで原文のファイルから翻訳
    対象を抽出し, カタログのテンプレートファイル (.pot
    ファイル) を作成する.
    翻訳対象とするかどうかはSphinxが決めている.
    [設計観点] 翻訳対象とされていない対象も翻訳した
    くなったらどうするか?
    案1: (前出の) 翻訳用ブランチ運用にして直接修
    正 ※ただし更新が頻繁だとツラい
    案2: SphinxプロジェクトにPull Requestを送る

    View Slide

  17. transifex-client &
    sphinx-intl
    Sphinx gettextで作成したカタログのテンプレート
    ファイルをtransifex-clientでTransifexにアップ
    ロードする.
    sphinx-intlでtransifex-clientの設定ファイル
    を生成して, .potファイルおよび.poファイル (後
    述) とTransifex上のリソース名の関連付けを行
    う.
    [設計観点] (特に無し)

    View Slide

  18. 翻訳
    アップロードされた.potファイルを元に, Transifexが翻訳作業画面に
    原文と訳文を記入するテキストボックスを表示してくれる.
    翻訳率表示, 用語集の参照・登録, 原文と訳文の齟齬のチェック
    (URL, 数字など) も行ってくれる.
    ただし, その機能がただのうるさいお節介になることもある.
    [設計観点] どの翻訳支援サービスを使うか?
    .pot, .poファイルに対応していることが前提.
    Transifex以外にはZanata, pootle等がある.
    エディタの使いやすさ, 自動化に向いたCLIツールの有無などから
    総合的に判断する.

    View Slide

  19. Transifexの画面
    実際のPython 3.6の翻訳作業画面

    View Slide

  20. (再び) transifex-client
    Transifexが翻訳結果から作成したカタログファイ
    ル (.poファイル) をダウンロードする.
    .potファイルは.poファイルのテンプレート
    .potファイルに翻訳結果や翻訳言語, 翻訳日時
    などのメタ情報を埋めたものが.poファイル
    [設計観点] (特に無し)

    View Slide

  21. Sphinx i18n
    原文 (正確には原文のdoctree) に翻訳を適用す
    る. 各フォーマットへの変換の部分は各ビルダーが行
    う.
    doctreeはreSTファイルの内容を木構造に変換
    し, 各節点にドキュメントの情報を持たせたもの.
    [設計観点] (特に無し)

    View Slide

  22. おまけ
    翻訳プロジェクトをやっていてよかったこと
    英語と英語の日本語訳作業に慣れる
    Pythonに貢献できる (Misc/ACKSに名前が載る)
    Sphinxに貢献できる (ツールを改善する経験)
    継続的デリバリー (CI) の経験が積める
    Python界隈での便利な名刺になる

    View Slide

  23. 結びとして
    PythonドキュメントはSphinxで成り立っている.
    況んや日本語訳プロジェクトをや!
    Sphinxの機能がユーザー側の要望で改善されていく
    のは, どちら側にとってもメリットになる.
    今後とも変わらぬお付き合いを是非ともよろしくお願
    いいたします!!! (to Sphinx Committers)
    ...

    View Slide

  24. 真の結びとして
    意訳: これからもたくさん質問・
    相談投げるのでヨロシク!!

    (to Sphinx Committers)

    View Slide