Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
Sphinx が支える翻訳ドキュメント
cocoatomo
PRO
February 15, 2018
Programming
0
1.6k
Sphinx が支える翻訳ドキュメント
Sphinx が Python ドキュメントおよびその日本語訳をどう支えているかについて
cocoatomo
PRO
February 15, 2018
Tweet
Share
More Decks by cocoatomo
See All by cocoatomo
みんなの知らない翻訳の世界
cocoatomo
PRO
0
540
Sphinx/docutilsの光と闇
cocoatomo
PRO
1
640
PyPy における静的解析
cocoatomo
PRO
0
100
型とは何か
cocoatomo
PRO
0
87
Other Decks in Programming
See All in Programming
Qiita Night PHP 2023
fuwasegu
0
830
ちょうぜつ改め21世紀ふつうのソフトウェア設計
tanakahisateru
7
6k
中小企業開発事例から見るサーバーレス
seike460
PRO
4
1.5k
xarray-Datatree: Hierarchical Data Structures for Multi-Model Science
tomnicholas
0
200
TypeScript 4.9のas const satisfiesが便利
tonkotsuboy_com
9
2.2k
ECS Service Connectでマイクロサービスを繋いでみた
xblood
0
520
TokyoR#103_DataProcessing
kilometer
0
460
Above All, Make It Fun! #fjordbootcamp / make it fun
kakutani
6
550
Cloudflare Workersと状態管理
chimame
2
450
様々なWebアプリをAzureにデプロイする
tomokusaba
0
110
SHOWROOMの分析目的を意識した伝え方・コミュニケーション
hatapu
0
230
AWSにおける標的型Bot対策
hacomono
0
390
Featured
See All Featured
Six Lessons from altMBA
skipperchong
15
2.3k
Designing for Performance
lara
601
65k
How GitHub (no longer) Works
holman
298
140k
Support Driven Design
roundedbygravity
88
8.9k
5 minutes of I Can Smell Your CMS
philhawksworth
198
18k
From Idea to $5000 a Month in 5 Months
shpigford
374
44k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
22
1.7k
A Philosophy of Restraint
colly
193
15k
Ruby is Unlike a Banana
tanoku
93
9.5k
GraphQLの誤解/rethinking-graphql
sonatard
39
7.8k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
7
560
Statistics for Hackers
jakevdp
785
210k
Transcript
Sphinxが支える 翻訳ドキュメント 2017.11.28 @cocoatomo
アジェンダ お前誰よ 想定読者 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, 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 その上, 常にアップデートされている
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 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ドメインで公開さ れている
翻訳ドキュメントが できるまで いったいどんなことが行われているのか? ???
翻訳プロジェクトの始め方 翻訳プロジェクトを始めるにあたり考えること 原文と訳文は1対1か? 脚注, 訳注の追加や文章の 順序の入れ替えをしたいか? →1対1でないならSphinxを使うのを諦める 翻訳作業は1回きりなのか継続的に行うのか? 翻訳プロジェクトを管理する上で困難な点は何か? 困難な点をフォローするために,
どのツールやサービ スを使って, どんな運用をしていくのか?
2種類の翻訳作業 単発型 ある時点での固定化された原文に対しての翻訳作業. 基本 的に翻訳は一度きり. 例: 記事, 書籍の翻訳など. 継続型 時間の経過とともに変化する原文に追随していく翻訳作業.
訳文は随時更新されていく. 例: ライブラリのドキュメントの 翻訳など. ⇒単発型よりも継続型の方が管理が面倒. 単発型では, 原文 のコメントアウトand訳文の直書きで済ませてもよい. 以降の解説では主に継続型を主眼に置く.
翻訳作業の困難さ 原文の管理 (必要なら) 更新の取り込み 訳文の管理 原文と訳文の対応付け 複数人作業による翻訳作業の衝突回避 翻訳 訳語の統一 表現の統一
(特に複数人作業)
翻訳作業を支える 機能・サービス Version Control System (Git) → 原文と訳文の更新を記録 カタログ作成ツール (Sphinx
gettext) → 翻訳対象の抽出および 原文と訳文の対応を管理 翻訳支援サービス (Transifex) 統合翻訳環境 → 翻訳作業に必要な機能を画面に配備 用語集 → 訳語の統一 原文が似ている訳文の提案 (翻訳メモリ) → 表現の統一 TransifexのCLIツール (transifex-client, sphinx-intl) 翻訳適用ツール (Sphinx i18n)
翻訳ドキュメントができるまで Transifex fork Sphinx gettext transifex- client transifex- client 翻訳
sphinx- intl Sphinx i18n
翻訳ドキュメントが できるまで ゴチャゴチャしてたので工程を1つずつ説明 処理フローの設計観点も含めつつ
fork (GitHub) 文字通り, 原文のファイル一式を翻訳プロジェクト用にforkする. [設計観点] 原文のブランチに追従する翻訳ブランチをどうするか? 案1: 原文と同名ブランチ (基本的にファイルを一切いじらない) Sphinx
i18nで原文ファイルとカタログファイルを分離して管理 翻訳対象でない部分の翻訳は諦める 案2: 翻訳用ブランチ (必要であれば原文のファイルもいじる) 独自の仕組みを導入しやすい 例: Pythonドキュメントの「原文」リンク 独自の仕組みの部分が原文と乖離しやすく, 追従がツラい
Sphinx gettext Sphinxのgettextビルダーで原文のファイルから翻訳 対象を抽出し, カタログのテンプレートファイル (.pot ファイル) を作成する. 翻訳対象とするかどうかはSphinxが決めている. [設計観点]
翻訳対象とされていない対象も翻訳した くなったらどうするか? 案1: (前出の) 翻訳用ブランチ運用にして直接修 正 ※ただし更新が頻繁だとツラい 案2: SphinxプロジェクトにPull Requestを送る
transifex-client & sphinx-intl Sphinx 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-client Transifexが翻訳結果から作成したカタログファイ ル (.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)