Python Monthly Topics

Python公式ドキュメントを翻訳しよう

鈴木たかのり@takanoryです。今月の「Python Monthly Topics」では、Pythonを使っている人なら誰でも一度はお世話になったことがある、Python公式ドキュメントhttps://docs.python.org/ja/3/を翻訳しよう!という内容でお届けします。

Python公式ドキュメントの翻訳は、やる気があればどなたでも参加できます。本記事ではオープンソースへの身近な貢献として「ドキュメント翻訳」という手段を紹介し、その詳細な手順や注意点などについて解説します。

Python公式ドキュメント
Python公式ドキュメント

Python公式ドキュメントを翻訳する

まずはPython公式ドキュメントを翻訳する基本的な流れと、それぞれの手順を説明します。

翻訳の基本的な流れ

Python公式ドキュメントを翻訳するための基本的な流れは以下のとおりです。

  1. Transifexでアカウントを作成: 翻訳を行うWebサイトのTransifexにアカウントを作成します
  2. 翻訳できる状態にする: 作成したアカウントでPython公式ドキュメントを翻訳できるように、管理者に設定してもらいます
  3. Trensifex上で翻訳を実施: Webサイト上で任意のテキストを翻訳します
  4. 公式ドキュメントに反映: 定期的に、Transifexから翻訳データを取得して公式ドキュメントに反映されます

それぞれ、具体的にどういうことをするのかを説明します。

Transifexでアカウントを作成

まずは翻訳を行うWebサイトTransifexhttps://www.transifex.com/にアカウントを作成します。Transifexは翻訳を共同で行うためのWebサイトで、さまざまなオープンソースのプロジェクトで使用されています。また、オープンソースだけではなく商用のサービスでも利用されています。

Transifex
Transifex

ここではオープンソース用のTransifexアカウントを作成します。アカウントは以下のURLから作成できます。

アカウントはGoogle、GitHub、LinkedIn、Facebookでのサインアップができます。もしくは、ユーザー名、メールアドレス、パスワードを入力したアカウント作成ができます。

翻訳できる状態にする

アカウントを作成したら、このアカウントでPythonの公式ドキュメントを翻訳できるようにする必要があります。公式ドキュメントの日本語の翻訳については、以下のGitHubのリポジトリに情報があります。READMEに記述されているとおり、管理者に連絡を行って設定をしてもらうことで、公式ドキュメントの翻訳ができるようになります。

手順は以下の通りです。

  • 連絡用のPython.jp Discordサーバに参加する
  • #python-doc-jaチャンネルに参加する
  • DiscordのDMで管理者のcocoatomoさんにメールアドレスとTransifexのアカウント名を連絡する

設定が終わると連絡が来るので、それまで待ちましょう。もし何か問題があった場合は#python-doc-jaチャンネルで相談するとよいと思います(筆者もアクティブではないですがtakanoryというアカウントでDiscordにいます⁠⁠。

Trensifex上で翻訳を実施

連絡がきたらTransifexにログインして、あとは粛々と翻訳を進めます。基本的な翻訳の進め方について簡単に説明します。

ログインすると右上に翻訳の組織(プロジェクトのようなもの)が切り替えられるようになっています。ここでPython document translationsが選択肢に増えているので、選択します。

組織を選択
組織を選択

するとPythonの公式ドキュメント翻訳の組織に移動します。画面の左側にPythonバージョンごとにプロジェクトが分かれているので、翻訳対象のバージョンを選択します。2023年8月現在は「Python」を選択するとPython 3.12の公式ドキュメントが対象になります。ここでは「Python」を選択します。

プロジェクトの一覧
プロジェクトの一覧

「Python」を選択した画面で翻訳されている言語の一覧が表示されます。この画面では上から3番目の「Japanese (ja)」にマウスカーソルを移動し、⁠翻訳」ボタンをクリックして、リソース一覧画面に遷移します。

Japaneseの「翻訳」ボタンをクリック
Japaneseの「翻訳」ボタンをクリック

リソース一覧画面では、選択したプロジェクト(ここではPython)の翻訳リソースの一覧が表示されます。⁠about」⁠bugs」⁠c-api--abstract」などがありますが、これはPython公式ドキュメントのファイル名と対応しています。例にあげた3つのリソースは、それぞれ以下のページと対応しています。

リソース名c-api--abstract等)が公式ドキュメントのURLc-api/abstract.html等)と似ていることがわかります。

リソースの一覧
リソースの一覧

自分が翻訳したいリソースを選択します。リソースの一覧を見ると「0件の未翻訳の文字列」⁠29件の未翻訳の文字列」のように、未翻訳の数がわかります。その数を見て翻訳対象のリソースを決める方法もありますが、Python公式ドキュメントを見て「このドキュメントを翻訳しよう」と決めて着手する方が一般的だと思います。

ここでは標準ライブラリのdatetimeのドキュメントを翻訳してみたいと思います。検索ボックスに文字列を入力すると、リソースを名前で絞り込めます。⁠library--datetime」が対象のリソースなのでクリックします。

リソースを検索
リソースの一覧

リソースを選択すると対象リソースの翻訳画面に遷移します。この画面が翻訳をするときに最も使用する画面です。画面の要素が多いので少し詳しく説明します。

datetimeの翻訳画面
datetimeの翻訳画面

翻訳画面でよく使う要素としては以下のものがあります。なお、各要素に付けている名前は私が便宜上付けた名前で、Transifexの公式の名前ではありません。

  1. フィルターメニュー:翻訳対象となるテキストの数、未翻訳、レビュー待ちの数が表示される。たとえば「未翻訳」をクリックすると、未翻訳のみに絞り込まれる
  2. 絞り込み:テキスト等を入力して絞り込める
  3. 文字列リスト:左に原文(翻訳対象のテキスト⁠⁠、右に翻訳文(翻訳されたテキスト)が表示される。翻訳したいテキストをクリックすると編集エリアに内容が表示される
  4. 編集エリア:上に原文が表示され、下に対応する翻訳文を書き込む
  5. 提案エリア:翻訳文の提案がある場合に表示される。詳細な使い方はあとで説明する
翻訳画面の解説
翻訳画面の解説

ここでは簡単な例として、Python 3.12でdatetimeに追加された%:zというディレクティブに関する説明を翻訳します。フィルターメニューや絞り込みを使用して原文のテキストを探し、提案を参考にしながら%:z が追加されました。」という翻訳文を入力して保存します。

以下の動画は、次の手順でTransifexを操作して翻訳をしています。

  • フィルターメニューで「未翻訳」のみに絞り込み
  • 原文%:z was added.」を探してクリック
  • 編集エリアに翻訳文%:z が追加されました。」を入力
  • 「翻訳を保存」ボタンをクリックして、翻訳文を保存
翻訳テキストを作成して保存
翻訳テキストを作成して保存

これで1つのテキストが翻訳されました! あとは他の翻訳できそうなテキストを探して、翻訳を進めていくだけです。

Transifexの使いこなし

Transifexには、翻訳を進める上で便利な機能があります。いくつかその機能と操作方法を紹介します。

原文をそのまま翻訳文にコピーする

原文の中には、Pythonのコードやモジュールのみといったように、翻訳できないものもあります。その場合はテキストをそのままコピーして、翻訳文として使用します。

次の例は、datetimeのドキュメントにある「zoneinfo」というテキストを翻訳する例です。編集エリアにある「原文をコピー」ボタンを押してコピーし、そのまま翻訳文として保存できます。

原文をコピー
原文をコピー

また、原文のコピーはまとめて実行もできます。次の例では、re --- 正規表現操作を翻訳しています。正規表現の新しいシンタックスとして*?+???などが未翻訳ですが、これらも原文をコピーして翻訳文としたいと思います。

画面左側の「文字列リスト」で複数の原文をチェックすると、画面右側に「Bulk actions」が表示されます。⁠Bulk actions」では複数の原文にまとめて処理が行え、⁠原文をコピー」ボタンをクリックすると、原文が翻訳文に一度にコピーされます。

原文をまとめてコピー
原文をまとめてコピー

翻訳文の提案を参考にする

未翻訳の原文ですが、その中には「原文が少しだけ変更」されたために、未翻訳状態になっているものが多数あります。その場合に便利な機能がTransifexにはあります。

ここでは標準ライブラリの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>`_.
unicodedataの未翻訳
unicodedataの未翻訳

画面右側の「提案エリア」を見てみると、⁠99% match」というほぼ一致している文章が提案されています。99% matchがどういうことかというと「翻訳しようとしている原文と99%一致している(似ている)原文がある」ため、その原文と翻訳文を表示しています。なお、どの程度原文が一致しているかによってパーセントの値が変わります。

99% matchしている原文とその翻訳文
99% matchしている原文とその翻訳文

このような場合は、原文の差分を確認し、必要であれば翻訳文を修正します。提案にマウスオーバーすると「→←」のようなアイコンが表示されます。このアイコンをクリックすると、2つの原文の差分が確認できます。この場合はUCD(ユニコード文字データベース)のバージョンが14.0.0から15.0.0に変わったことがわかります。

2つの原文の差分を確認
2つの原文の差分を確認

あとは99% matchしている翻訳文の「使用する」をクリックしてコピーし、14.0.015.0.0に書き換えてから「翻訳を保存」すれば完了です。

99% matchの翻訳文を使用して書き換える
99% matchの翻訳文を使用して書き換える

このように、以前の公式ドキュメントから、ほんの少しだけ書き換わっている原文がたくさんあります。たとえば、URLがhttp:からhttps:に変わっていたり、Mac OSmacOSに変わっているだけといったものもあります。こういった細かい修正による翻訳漏れに対応するだけでも、公式ドキュメントの翻訳に貢献していると言えると思います。

翻訳のはじめ方⁠気をつけること

ここでは翻訳のはじめ方としてお勧めの方法や、ドキュメント翻訳をする上でのメリット、気をつけることについて書きます。

翻訳のはじめ方

まずは、⁠翻訳文の提案を参考にする」にあるように、少しだけ書き換わったところ、似た言い回しがあるところから翻訳を始めることをお勧めします。最初から難しい長文の翻訳に挑戦すると、そこでくじけてしまうこともあると思います。簡単な翻訳から着手することで、翻訳作業に少しずつ慣れていくとよいと思います。

翻訳をするメリット

次にドキュメントを翻訳するメリットですが、まず第一にPythonへの貢献が挙げられます。翻訳することによって、日本語で公式ドキュメントを読む他の人への助けになります。

また、副次的な効果としてPythonに対しての理解が深くなるというメリットがあります。そもそも翻訳文がない原文は、Pythonのバージョンアップに際して更新された処理が多いです。先ほどの例で言うとdatetimeの%:zや、正規表現の*?+???などです。翻訳をすることで、Pythonの新機能や変更を知ることができ、Python自体への理解が深まります。

気をつけること

翻訳をするときに気をつける点として機械翻訳を使わないということがあります。機械翻訳はその翻訳した文章を再利用するライセンスに問題がある場合が多いため、使用しないでください。ただし、当然ですが辞書をたくさん引きます。

また、ある単語をどのように訳すか悩むことがよくあると思います。その場合は公式ドキュメントで同じ単語をどのように翻訳しているかを参考にしましょう。英語の公式ドキュメントで同じ単語を、どのように翻訳しているかを参考にして、全体として統一のある訳語にしましょう。

悩んだ場合は人に相談するのもおすすめです。Python.jpのDiscordには「#python-doc-ja」というチャンネルがあります。悩んだときにはこのチャンネルで「この原文をこう訳そうと思いますがどうでしょう?」という風に相談してみるのも1つの手だと思います。

翻訳は時間をかけただけ確実に進みます。ぜひチャレンジしてみたいなと思った方は、少しずつ翻訳を進めてくれるとうれしいです。

裏側の仕組み

ここでは少し視点を変えて、Python公式ドキュメントがどういった仕組みで多言語のサイトとして公開されているかを説明します。

公式ドキュメントはSphinx製

Pythonの公式ドキュメントはSphinxというツールで作成されています。SphinxはreStructuredTextMarkdownという軽量マークアップ言語で作成したテキストを、HTMLやePub、PDFとして出力できるドキュメンテーションツールです。

SphinxはPython公式ドキュメントだけではなく、多くのPythonのライブラリの公式ドキュメントやWebサイトで活用されています。一例をあげるとpipFlake8pandasRequestsなどのドキュメントもSphinxで作成されています。また、筆者が所属する一般社団法人PyCon JP AssociationのWebサイトwww.pycon.jpPython Boot CampテキストもSphinx製です。

Python公式ドキュメントの元となるテキストを見てみましょう。GitHubのpython/cpython/Docに公式ドキュメントがあります。about.rstというファイルの中身を見てみると、以下のような内容になっています。

about.rst - https://github.com/python/cpython/blob/main/Doc/about.rst
=====================
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.rstに対応したページはhttps://docs.python.org/3/about.htmlです。ページを見てみるとAbout these documentsが見出しになってり、行頭に* がある行が箇条書きになっていることがわかります。このように、テキストに===* といった簡単なマークアップをすることで、HTMLとしてきれいなドキュメントを出力できることがSphinxの特徴です。

https://docs.python.org/3/about.htmlのページ
 https://docs.python.org/3/about.html のページ

Sphinxドキュメントの国際化

しかし、このabout.rstファイルは英語のドキュメントのみです。日本語のページはどのように作成しているのでしょうか? Sphinxにはドキュメントの国際化機能が内蔵されており、この機能を使用して公式ドキュメントは多言語化されています。

Sphinxの国際化には、ソフトウェアの国際化によく使用されているgettextの仕組みを利用しています。gettextでは翻訳対象となる原文のリストを持つpotファイルと、訳文を記入したpoファイルからなります。たとえば先ほどのabout.rstを元に作成されたpotファイルは以下のような内容になります。msgidにabout.rstにある英文が入ります。

#: ../../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公式ドキュメントも公開されています。

さまざまな言語に対応したPython公式ドキュメント
さまざまな言語に対応したPython公式ドキュメント

Transifexはmsgidを原文として表示し、入力した訳文をmsgstrとして保存する」という処理をするWebシステムと言えます。

なお、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公式ドキュメントや他の翻訳プロジェクトで「ここが翻訳されていないな」と気づいたら、ぜひ翻訳に挑戦してみてください。

おすすめ記事

記事・ニュース一覧