鈴木たかのり
Python公式ドキュメントの翻訳は、やる気があればどなたでも参加できます。本記事ではオープンソースへの身近な貢献として
Python公式ドキュメントを翻訳する
まずはPython公式ドキュメントを翻訳する基本的な流れと、それぞれの手順を説明します。
翻訳の基本的な流れ
Python公式ドキュメントを翻訳するための基本的な流れは以下のとおりです。
- Transifexでアカウントを作成: 翻訳を行うWebサイトのTransifexにアカウントを作成します
- 翻訳できる状態にする: 作成したアカウントでPython公式ドキュメントを翻訳できるように、管理者に設定してもらいます
- Trensifex上で翻訳を実施: Webサイト上で任意のテキストを翻訳します
- 公式ドキュメントに反映: 定期的に、Transifexから翻訳データを取得して公式ドキュメントに反映されます
それぞれ、具体的にどういうことをするのかを説明します。
Transifexでアカウントを作成
まずは翻訳を行うWebサイトTransifex
ここではオープンソース用のTransifexアカウントを作成します。アカウントは以下のURLから作成できます。
アカウントはGoogle、GitHub、LinkedIn、Facebookでのサインアップができます。もしくは、ユーザー名、メールアドレス、パスワードを入力したアカウント作成ができます。
翻訳できる状態にする
アカウントを作成したら、このアカウントでPythonの公式ドキュメントを翻訳できるようにする必要があります。公式ドキュメントの日本語の翻訳については、以下のGitHubのリポジトリに情報があります。READMEに記述されているとおり、管理者に連絡を行って設定をしてもらうことで、公式ドキュメントの翻訳ができるようになります。
手順は以下の通りです。
- 連絡用のPython.
jp Discordサーバ に参加する- Python.
jp Discordへの参加リンク: https:// discord. gg/ M5NdnCV
- Python.
#python-doc-jaチャンネルに参加する- DiscordのDMで管理者の
cocoatomoさんにメールアドレスとTransifexのアカウント名を連絡する
設定が終わると連絡が来るので、それまで待ちましょう。もし何か問題があった場合は#python-doc-jaチャンネルで相談するとよいと思いますtakanoryというアカウントでDiscordにいます）。
Trensifex上で翻訳を実施
連絡がきたらTransifexにログインして、あとは粛々と翻訳を進めます。基本的な翻訳の進め方について簡単に説明します。
ログインすると右上に翻訳の組織Python document translationsが選択肢に増えているので、選択します。
するとPythonの公式ドキュメント翻訳の組織に移動します。画面の左側にPythonバージョンごとにプロジェクトが分かれているので、翻訳対象のバージョンを選択します。2023年8月現在は
「Python」
リソース一覧画面では、選択したプロジェクト
- このドキュメントについて：https://
docs. python. org/ ja/ 3. 12/ about. html - バグへの対処：https://
docs. python. org/ ja/ 3. 12/ bugs. html - 抽象オブジェクトレイヤ：https://
docs. python. org/ ja/ 3. 12/ c-api/ abstract. html
リソース名c-api--abstract等）c-api/等）
自分が翻訳したいリソースを選択します。リソースの一覧を見ると
ここでは標準ライブラリのdatetimeのドキュメントを翻訳してみたいと思います。検索ボックスに文字列を入力すると、リソースを名前で絞り込めます。
リソースを選択すると対象リソースの翻訳画面に遷移します。この画面が翻訳をするときに最も使用する画面です。画面の要素が多いので少し詳しく説明します。
翻訳画面でよく使う要素としては以下のものがあります。なお、各要素に付けている名前は私が便宜上付けた名前で、Transifexの公式の名前ではありません。
- ① フィルターメニュー：翻訳対象となるテキストの数、未翻訳、レビュー待ちの数が表示される。たとえば
「未翻訳」 をクリックすると、未翻訳のみに絞り込まれる - ② 絞り込み：テキスト等を入力して絞り込める
- ③ 文字列リスト：左に原文
（翻訳対象のテキスト）、右に翻訳文 （翻訳されたテキスト） が表示される。翻訳したいテキストをクリックすると編集エリアに内容が表示される - ④ 編集エリア：上に原文が表示され、下に対応する翻訳文を書き込む
- ⑤ 提案エリア：翻訳文の提案がある場合に表示される。詳細な使い方はあとで説明する
ここでは簡単な例として、Python 3.%:zというディレクティブに関する説明を翻訳します。フィルターメニューや絞り込みを使用して原文のテキストを探し、提案を参考にしながら%:z が追加されました。」
以下の動画は、次の手順でTransifexを操作して翻訳をしています。
- フィルターメニューで
「未翻訳」 のみに絞り込み - 原文
「 %:zwas added.」を探してクリック - 編集エリアに翻訳文
「 %:zが追加されました。」を入力 - 「翻訳を保存」
ボタンをクリックして、翻訳文を保存
これで1つのテキストが翻訳されました！ あとは他の翻訳できそうなテキストを探して、翻訳を進めていくだけです。
Transifexの使いこなし
Transifexには、翻訳を進める上で便利な機能があります。いくつかその機能と操作方法を紹介します。
原文をそのまま翻訳文にコピーする
原文の中には、Pythonのコードやモジュールのみといったように、翻訳できないものもあります。その場合はテキストをそのままコピーして、翻訳文として使用します。
次の例は、datetimeのドキュメントにある
また、原文のコピーはまとめて実行もできます。次の例では、re --- 正規表現操作を翻訳しています。正規表現の新しいシンタックスとして*?、+?、??などが未翻訳ですが、これらも原文をコピーして翻訳文としたいと思います。
画面左側の
翻訳文の提案を参考にする
未翻訳の原文ですが、その中には
ここでは標準ライブラリのunicodedataを例に見てみます。翻訳リソースの未翻訳を見てると、1つだけ未翻訳があります。原文は以下の内容です。
This module provides access to the Unicode Character Database (UCD) which defines character
properties for all Unicode characters. The data contained in this database is compiled from
the `UCD version 15.0.0 <https://www.unicode.org/Public/15.0.0/ucd>`_.
画面右側の
このような場合は、原文の差分を確認し、必要であれば翻訳文を修正します。提案にマウスオーバーすると14.から15.に変わったことがわかります。
あとは99% matchしている翻訳文の14.を15.に書き換えてから
このように、以前の公式ドキュメントから、ほんの少しだけ書き換わっている原文がたくさんあります。たとえば、URLがhttp:からhttps:に変わっていたり、Mac OSがmacOSに変わっているだけといったものもあります。こういった細かい修正による翻訳漏れに対応するだけでも、公式ドキュメントの翻訳に貢献していると言えると思います。
翻訳のはじめ方・気をつけること
ここでは翻訳のはじめ方としてお勧めの方法や、ドキュメント翻訳をする上でのメリット、気をつけることについて書きます。
翻訳のはじめ方
まずは、
翻訳をするメリット
次にドキュメントを翻訳するメリットですが、まず第一にPythonへの貢献が挙げられます。翻訳することによって、日本語で公式ドキュメントを読む他の人への助けになります。
また、副次的な効果としてPythonに対しての理解が深くなるというメリットがあります。そもそも翻訳文がない原文は、Pythonのバージョンアップに際して更新された処理が多いです。先ほどの例で言うとdatetimeの%:zや、正規表現の*?、+?、??などです。翻訳をすることで、Pythonの新機能や変更を知ることができ、Python自体への理解が深まります。
気をつけること
翻訳をするときに気をつける点として機械翻訳を使わないということがあります。機械翻訳はその翻訳した文章を再利用するライセンスに問題がある場合が多いため、使用しないでください。ただし、当然ですが辞書をたくさん引きます。
また、ある単語をどのように訳すか悩むことがよくあると思います。その場合は公式ドキュメントで同じ単語をどのように翻訳しているかを参考にしましょう。英語の公式ドキュメントで同じ単語を、どのように翻訳しているかを参考にして、全体として統一のある訳語にしましょう。
悩んだ場合は人に相談するのもおすすめです。Python.
翻訳は時間をかけただけ確実に進みます。ぜひチャレンジしてみたいなと思った方は、少しずつ翻訳を進めてくれるとうれしいです。
裏側の仕組み
ここでは少し視点を変えて、Python公式ドキュメントがどういった仕組みで多言語のサイトとして公開されているかを説明します。
公式ドキュメントはSphinx製
Pythonの公式ドキュメントはSphinxというツールで作成されています。SphinxはreStructuredTextやMarkdownという軽量マークアップ言語で作成したテキストを、HTMLやePub、PDFとして出力できるドキュメンテーションツールです。
SphinxはPython公式ドキュメントだけではなく、多くのPythonのライブラリの公式ドキュメントやWebサイトで活用されています。一例をあげるとpip、Flake8、pandas、RequestsなどのドキュメントもSphinxで作成されています。また、筆者が所属する一般社団法人PyCon JP AssociationのWebサイトwww.
Python公式ドキュメントの元となるテキストを見てみましょう。GitHubのpython/about.というファイルの中身を見てみると、以下のような内容になっています。
=====================
About these documents
=====================
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Sphinx: https://www.sphinx-doc.org/
.. In the online version of these documents, you can submit comments and suggest
changes directly on the documentation pages.
Development of the documentation and its toolchain is an entirely volunteer
effort, just like Python itself. If you want to contribute, please take a
look at the :ref:`reporting-bugs` page for information on how to do so. New
volunteers are always welcome!
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
and writer of much of the content;
* the `Docutils <https://docutils.sourceforge.io/>`_ project for creating
reStructuredText and the Docutils suite;
* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
got many good ideas.
（以下省略）
このabout.に対応したページはhttps://About these documentsが見出しになってり、行頭に* がある行が箇条書きになっていることがわかります。このように、テキストに===や* といった簡単なマークアップをすることで、HTMLとしてきれいなドキュメントを出力できることがSphinxの特徴です。
Sphinxドキュメントの国際化
しかし、このabout.ファイルは英語のドキュメントのみです。日本語のページはどのように作成しているのでしょうか？ Sphinxにはドキュメントの国際化機能が内蔵されており、この機能を使用して公式ドキュメントは多言語化されています。
Sphinxの国際化には、ソフトウェアの国際化によく使用されているgettextの仕組みを利用しています。gettextでは翻訳対象となる原文のリストを持つpotファイルと、訳文を記入したpoファイルからなります。たとえば先ほどのabout.を元に作成されたpotファイルは以下のような内容になります。msgidにabout.
#: ../../about.rst:3
msgid "About these documents"
msgstr ""
#: ../../about.rst:6
msgid ""
"These documents are generated from `reStructuredText`_ sources by `Sphinx`_,"
" a document processor specifically written for the Python documentation."
msgstr ""
このファイルを日本語に翻訳する場合は、訳文をmsgstrの部分に記入します。これで原文と訳文の対応が取れます。
#: ../../about.rst:3
msgid "About these documents"
msgstr "このドキュメントについて"
#: ../../about.rst:6
msgid ""
"These documents are generated from `reStructuredText`_ sources by `Sphinx`_,"
" a document processor specifically written for the Python documentation."
msgstr ""
"このドキュメントは、 Python のドキュメントを主要な目的として作られた ドキュメントプロセッサの `Sphinx`_ を利用して、 "
"`reStructuredText`_ 形式のソースから生成されました。"
あとは国際化の仕組みにより、Sphinxがpoファイルを読み込んで日本語に翻訳されたドキュメントを生成しています。同様に他の言語のpoファイルもあるため、フランス語やスペイン語に翻訳されたPython公式ドキュメントも公開されています。
Transifexはmsgidを原文として表示し、入力した訳文をmsgstrとして保存する」
なお、Pythonのドキュメントに関するフォーラムで、TransifexからWeblateという別翻訳プラットフォームに変更しないか？
Python関連の翻訳プロジェクト
Python公式ドキュメント以外にも翻訳プロジェクトはあります。以下にいくつか筆者が見つけたものを紹介します。自身が使っている、興味があるライブラリ、フレームワークに対する貢献の第一歩として、翻訳に参加してみるのもおすすめです。
- Django ドキュメント
- WebアプリケーションフレームワークであるDjangoの公式ドキュメントの翻訳プロジェクトです。下記のページに参加方法が書いてあります。
- Django Girls のチュートリアル
- Django Girlsという女性向けにDjangoのチュートリアルを運営するグループが公開している、Djangoの初心者向けチュートリアルです。このドキュメントは男性でも利用できますし、翻訳も参加できます。翻訳は以下のサイトで行っています。
- PyPI - The Python Package Index
- Pythonのパッケージを配布するサイトですが、多言語化されています。翻訳は以下のサイトで行っています。
- Sphinx documentation
- Python公式ドキュメントでも使用しているSphinxのドキュメントも多言語化されています。翻訳は以下のサイトで行っています。
- Internationalization and Localization — JupyterLab 4.
0.3 documentation - JupyterLabを多言語化する言語パックの翻訳プロジェクトです。翻訳は以下のサイトで行っています。
まとめ
普段利用しているPython公式ドキュメントが、どのように翻訳されて公開されているのか、その裏側を知ることができたと思います。身近なオープンソースへの貢献として翻訳という方法があるということも知ってもらえたと思います。
Python公式ドキュメントや他の翻訳プロジェクトで