Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Sphinx が支える翻訳ドキュメント
Search
cocoatomo
February 15, 2018
Programming
0
2.7k
Sphinx が支える翻訳ドキュメント
Sphinx が Python ドキュメントおよびその日本語訳をどう支えているかについて
cocoatomo
February 15, 2018
Tweet
Share
More Decks by cocoatomo
See All by cocoatomo
みんなの知らない翻訳の世界
cocoatomo
0
790
Sphinx/docutilsの光と闇
cocoatomo
1
850
PyPy における静的解析
cocoatomo
0
150
型とは何か
cocoatomo
0
110
Other Decks in Programming
See All in Programming
Goで実践するドメイン駆動開発 AIと歩み始めた新規プロダクト開発の現在地
imkaoru
4
840
CSC305 Lecture 06
javiergs
PRO
0
230
タスクの特性や不確実性に応じた最適な作業スタイルの選択(ペアプロ・モブプロ・ソロプロ)と実践 / Optimal Work Style Selection: Pair, Mob, or Solo Programming.
honyanya
3
170
理論と実務のギャップを超える
eycjur
0
140
PHPに関数型の魂を宿す〜PHP 8.5 で実現する堅牢なコードとは〜 #phpcon_hiroshima / phpcon-hiroshima-2025
shogogg
1
220
スマホから Youtube Shortsを見られないようにする
lemolatoon
27
32k
「ちょっと古いから」って避けてた技術書、今だからこそ読もう
mottyzzz
10
6.7k
私達はmodernize packageに夢を見るか feat. go/analysis, go/ast / Go Conference 2025
kaorumuta
2
560
詳しくない分野でのVibe Codingで困ったことと学び/vibe-coding-in-unfamiliar-area
shibayu36
3
5k
組込みだけじゃない!TinyGo で始める無料クラウド開発入門
otakakot
0
270
技術的負債の正体を知って向き合う / Facing Technical Debt
irof
0
170
TFLintカスタムプラグインで始める Terraformコード品質管理
bells17
2
170
Featured
See All Featured
Principles of Awesome APIs and How to Build Them.
keavy
127
17k
Context Engineering - Making Every Token Count
addyosmani
6
250
Bash Introduction
62gerente
615
210k
Keith and Marios Guide to Fast Websites
keithpitt
411
23k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
32
1.6k
Being A Developer After 40
akosma
91
590k
Why Our Code Smells
bkeepers
PRO
340
57k
The Invisible Side of Design
smashingmag
302
51k
Six Lessons from altMBA
skipperchong
29
4k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
252
21k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
3.1k
Facilitating Awesome Meetings
lara
56
6.6k
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)