Python パッケージングガイドの翻訳ガイド#

このガイドは Python パッケージングガイドの翻訳への貢献を始めるのに役立ちます。

ガイドの翻訳に貢献するプロセスは、ガイドのソースファイルに直接取り組むのではなく、翻訳ファイルに取り組むという点を除けば、ガイドそのものに貢献するプロセスと似ています。

翻訳プロセスの概要#

ソフトウェアを異なる言語に適応させるプロセスは国際化、略してi18nと呼ばれます。国際化はソースコード、私たちの場合はガイドのオリジナルの英語のソースファイルを修正することなく翻訳が行われるようにします。

Pythonパッケージガイドをビルドするために使っているドキュメントエンジンであるSphinxは、国際化をビルトインでサポートしているので、ワークフローはとても簡単です。

ガイドを実際に異なる言語に翻訳するプロセスをローカリゼーション、略してl10nと呼びます。あなたが貢献するのはこのステップです。

ここでは、翻訳プロセスの概要を簡単に説明します:

このガイドはもともと英語で書かれており、MarkDownのファイル群に保存されています。
ソースファイルはSphinxによって処理され、各ターゲット言語のフォルダに格納された翻訳ファイルのセットを生成します。
（あなたのような!）貢献者は、これらのファイルをさまざまな言語に翻訳します。
ガイドがビルドされると、Sphinxはオリジナルの言語(英語)と、コンフィグレーションで定義された言語の翻訳版のガイドを作成します。

注釈

貢献するために技術的な詳細を理解する必要はありませんが、もしSphinxがどのように国際化とローカライズを処理するのかに興味があれば、ここに詳しい情報があります。

ローカル環境の設定#

作業を始める前に、ローカルの作業環境を設定する必要があります。

まず、ガイドリポジトリを個人のGitHubアカウントにフォークし、フォークしたリポジトリをローカルコンピューターにクローンします。

仮想環境を作成し、ガイドの開発依存関係をインストールするには、以下のコマンドを実行します:

$ cd ./python-package-guide
$ python -m venv .venv
$ source .venv/bin/activate
$ pip install .[dev]

TODO: このセクションは、より多くの作業が必要か、CONTRIBUTINGガイドへの参照に置き換える必要があります。

新しい言語の翻訳を始める#

既存の翻訳に手を加える場合は、このステップを飛ばして直接次のセクションに進んでください。

重要

新しい言語へのガイドの翻訳を開始したい場合は、リポジトリに issueを作成することから始めてください。

新しい言語の翻訳ファイルを生成するには、 noxfile.py 設定ファイルの LANGUAGES リストにその言語を追加します。 Nox はガイドとその翻訳のビルドを管理するために使うツールです。

noxfile.py の中で LANGUAGES リストを見つけて、対応する2文字のコードを追加します。例えば、フランス語への翻訳を開始したい場合は 'fr' を追加します:

## Localization options (translations)

# List of languages for which locales will be generated in (/locales/<lang>)
LANGUAGES = ["es", "fr"]

注釈

You can find a list of the two-letter Sphinx language option here.

翻訳ファイルの準備#

翻訳ファイルには、英語の原文と翻訳文を入力するスペースが含まれています。翻訳を始める前に、翻訳ファイルがガイドの最新の変更に対応していることを確認する必要があります。

You can do this by running the following command, replacing LANG by the language code you plan to work on (e.g., es for Spanish):

$ nox -s update-language -- LANG

このコマンドは、翻訳ファイルがまだ存在しない場合は作成し、すでに存在する場合は最新の変更内容で更新します。

翻訳ファイルは拡張子が .po のテキストファイルで、各言語に対応するフォルダ ./locales に格納されています。例えば、スペイン語の翻訳ファイルは locale/es/LC_MESSAGES ディレクトリに格納されています。

翻訳ファイルは、元の英文テキストと翻訳テキストを対応付けるため、 "catalog" ファイルや "portable object" ファイルと呼ばれることもあります。

注釈

翻訳するためにPOフォーマットの詳細をすべて知っている必要はありません。もっと詳しく知りたければ、 GNU gettext documentation に詳細があります。

翻訳作業#

翻訳を開始するには、翻訳したいターゲット言語に対応する ./locales 内のフォルダに移動します（例えば、スペイン語翻訳なら ./locale/es/LC_MESSAGES/ です）。

このフォルダには、ガイドの各セクションに対応する .po ファイルのセットがあります：

$ cd ./locales/es/LC_MESSAGES/
$ ls *.po

./locales/es/LC_MESSAGES/CONTRIBUTING.po
./locales/es/LC_MESSAGES/index.po
./locales/es/LC_MESSAGES/tests.po
./locales/es/LC_MESSAGES/tutorials.po
./locales/es/LC_MESSAGES/documentation.po
./locales/es/LC_MESSAGES/package-structure-code.po
./locales/es/LC_MESSAGES/TRANSLATING.po

注釈

また、同じフォルダにいくつかの .mo ファイルがあるかもしれません。これらはSphinxがビルド中に作成した .po ファイルをコンパイルしたもので、翻訳されたバージョンのガイドを生成するために使用されます。これらは中間的なファイルで、直接編集したり、リポジトリに保存したりするものではありません。

新しい翻訳をする場合は、.po ファイルを1つ選んで始めます。既存の翻訳をする場合は、最も作業が必要な .po ファイルから始めることができます。

各ファイルがどれくらい翻訳されたかを見るには、 sphinx-intl stat を使ってください。それぞれの .po ファイルに含まれる、翻訳された文字列、あいまいな文字列、未翻訳の文字列の数を見ることができます。

例えば、スペイン語翻訳の統計を見るには、次のように実行します:

$ sphinx-intl stat -l es

locales/es/LC_MESSAGES/tutorials.po: 0 translated, 0 fuzzy, 950 untranslated.
locales/es/LC_MESSAGES/TRANSLATING.po: 0 translated, 0 fuzzy, 44 untranslated.
locales/es/LC_MESSAGES/package-structure-code.po: 0 translated, 0 fuzzy, 885 untranslated.
locales/es/LC_MESSAGES/CONTRIBUTING.po: 0 translated, 0 fuzzy, 38 untranslated.
locales/es/LC_MESSAGES/documentation.po: 0 translated, 0 fuzzy, 430 untranslated.
locales/es/LC_MESSAGES/tests.po: 155 translated, 2 fuzzy, 3 untranslated.
locales/es/LC_MESSAGES/index.po: 88 translated, 0 fuzzy, 5 untranslated.

これらのカテゴリーは何を意味するのか:

Translated stringsは、ターゲット言語に翻訳された文字列です。
Fuzzy stringsとは、翻訳されたものの、ガイドの元の英語の文字列が変更されたため、見直しが必要な文字列のことです。
Untranslated stringsは、まだ翻訳されていない文字列です。

注釈

Sphinxが他の言語でガイドをビルドしている場合、 ./locales/ にある対応するフォルダを調べて、翻訳された文字列を探します。もし翻訳が利用可能であれば、Sphinxは英語のテキストをターゲット言語の同等のテキストに置き換えます。もし翻訳が利用できない場合、Sphinxはオリジナルの英語の文字列を使用します。

翻訳ファイルの編集#

.po`ファイルの編集にはどんなテキストエディタでも使えます。しかし、お好みであれば、 Poedit のようなグラフィックなインターフェースを提供するツールもあります。

お使いのエディタによっては、.poファイルを扱うためのシンタックスハイライトやその他の機能を提供するプラグインや拡張機能をインストールできるかもしれません。例えば、Visual Studio Codeの gettext エクステンションのようなものです。

.po`ファイルを開くと、次のようなエントリーが並んでいます:

#: ../../index.md:1
msgid "pyOpenSci Python Package Guide"
msgstr ""

エントリーの最初の行は #: で始まり、テキストが抽出された元のソースファイルと行番号への参照となります。この情報は、ガイド内のテキストの文脈を見つけるのに便利です。

msgid フィールドには翻訳が必要な元の英語のテキストを入力します。 msgstr フィールドには翻訳されたテキストを入力します。このフィールドには他の人がすでに翻訳したテキストが入っているかもしれません。

#: ../../index.md:1
msgid "pyOpenSci Python Package Guide"
msgstr "La guía de paquetes de Python de pyOpenSci"

英語の原文が1行では長すぎて、複数行に分かれている場合があります。このような場合、翻訳されたテキストでも同じ構造を保つことができます。以下の例の msgid フィールドと msgstr フィールドの両方が空文字列で始まっていることに注意してください。

#: ../../index.md:254
msgid ""
"Every page in this guidebook goes through an extensive community review "
"process. To ensure our guidebook is both beginner-friendly and accurate, "
"we encourage reviews from a diverse set of pythonistas and scientists "
"with a wide range of skills and expertise."
msgstr ""
"Cada página en esta guía es revisada extensamente por la "
"comunidad. Para asegurar que nuestra guía sea comprensible a los principiantes y "
"a la vez precisa, un conjunto diverso de desarrolladores y científicos con una amplia "
"gama de conocimientos y experiencia participa en el proceso."

英語のテキストには、太字や斜体などのMarkdown書式が含まれていることがあります。翻訳されたテキストで書式を維持する必要があります、フォーマットタグの中のテキストを翻訳してください。

英文テキストには、ガイドの他のセクションや外部リソースへのリンクが含まれている場合があります。リンクは翻訳されたテキストの中に残し、必要に応じてリンクテキストを更新してください。

#: ../../index.md:75
msgid "[What is a Python package?](/tutorials/intro)"
msgstr "[¿Que es un paquete de Python?](/tutorials/intro)"

エントリーには fuzzy と表示されることがありますが、これは原文の英文が翻訳後に変更され、翻訳を修正する必要があることを意味します。このような場合、エントリーに #, で始まる行が追加されます:

#: ../../tests/write-tests.md:84
#, fuzzy
msgid ""
"**Test special cases:** Sometimes there are special or outlier cases. For"
" instance, if a function performs a specific calculation that may become "
"problematic closer to the value = 0, test it with the input of both 0 and"
msgstr ""
"**Prueba casos especiales:** A veces hay casos especiales o atípicos. Por"
" ejemplo, si una función realiza un cálculo específico que puede tener "
"problemas cerca del valor = 0, pruébalo con la entrada de 0 y un valor"
" normal."

翻訳を確認して必要な変更を加え、翻訳に満足したら fuzzy タグを削除することができます。

文字で始まる行をエントリに追加することで、翻訳ファイルにコメントを追加することもできます。これは、他の翻訳者やレビュアーが翻訳を見るために文脈を追加するのに役立ちます、しかし、これは特別な状況でのみ必要かもしれません。

重要

翻訳作業をするときは、 msgid フィールドの元の英文を修正 しないで ください。もし原文に誤字や脱字があった場合は、原文のソースファイル（エントリーの1行目から探してください）を修正し、別途プルリクエストを提出してください。

翻訳されたドキュメントのビルド#

Once you finished translating or when you want to check the translation in context, you can build the guide locally on your computer, using the following command, replacing LANG by the proper language code (e.g., es for Spanish)

nox -s build-language -- LANG

このコマンドは noxfile.py の LANGUAGES リストで定義されたガイドの全ての翻訳版をビルドします。これらの翻訳版は _build/html に、言語コードにちなんだ名前(例えば es、fr など)のフォルダに保存されます。

ブラウザで翻訳版のガイドを見るには、対応する index.html ファイルを開いてください。例えば、スペイン語の翻訳版を見るには、 _build/html/es/index.html を開きます。

また、翻訳ファイルを変更すると自動的に更新されるガイドのライブバージョンをビルドすることもできます。これを行うには、nox -s docs-live-lang コマンドを使用します。この場合、ビルドしたい言語を指定する必要があることに注意してください。例えば、スペイン語翻訳に取り組んでいる場合、次のように実行します:

nox -s docs-live-lang -- es

Note the -- before the language code, it indicates that the following arguments should be passed into the nox session and not be interpreted directly by nox. If you forget the --, nox will look instead for a session named 'es' and raise an error that it does not exist.

このコマンドは sphinx-autobuild を使って、ローカルのWebサーバーを起動し、そこでガイドの翻訳版にアクセスすることができます。ブラウザで http://localhost:8000 に移動して、ガイドを開くことができます。

これは、翻訳ファイルに変更を加えながら、翻訳版のガイドがどのように見えるかを確認するのに最適な方法です。

貢献PRの提出#

翻訳が終わり、翻訳のプルリクエスト（PR）を提出する前に、翻訳されたバージョンのガイドがエラーや警告なしにビルドされ、ブラウザで正しく表示されることを確認する必要があります。

以下の手順に従ってください:

リリース時に使用されるのと同じパラメータでガイドの翻訳をビルドします:

nox -s build-all-languages-test

出力に警告やエラーがないことを確認してください。もしあれば、PRを提出する前に修正する必要があります。
_build/html/<lang>/index.html ファイルを開いて、翻訳版のガイドがブラウザでうまく表示されることを確認してください。 <lang> は作業中の言語です。

問題がなければ、変更内容をPRとして提出することができます。

注釈

翻訳のPRを提出する際は、1つの言語に対する変更のみを記載してください。複数の言語で翻訳した場合は、言語ごとにPRを提出してください。

翻訳PRには、識別とレビューを容易にするため、言語を示すラベルが付けられます。例えば、スペイン語翻訳への貢献には 'lang-es' というタグが付けられます。

TODO: This tagging could be automated with a GitHub Actions.

PRを提出する際には、あなたが行った変更についての簡単な説明と、レビュアーにとって参考になりそうな文脈（新しい文字列を翻訳した、あいまいなエントリーを見直した、誤字脱字を修正した、など）を必ず含めてください。

レビュープロセス#

翻訳貢献のレビュープロセスは、ガイドへの他のレビューのレビュープロセスと同様です。

TODO: このセクションは、私たちが採用するレビューのワークフローによって、もっと作業が必要です。他のプロジェクトでは、通常、言語ごとにコーディネーター/編集者を割り当て、その人が翻訳投稿のレビューとマージに責任を持ちます。

各言語には担当エディターがおり、翻訳投稿の確認と統合を担当します。エディターは、変更が正確で、ガイドのスタイルやトーンと一致していることを確認します。

エディターが翻訳を改善するために説明を求めたり、変更を提案したりすることがあります。このような場合は、要求された変更を行い、元のPRを投稿したブランチにプッシュしてください。

エディターが翻訳に満足したら、PRをマージします。ガイドの翻訳版は言語がリリースされ次第、pyOpenSciのウェブサイトから入手できます。

リリースのプロセス#

言語がリリース準備できたら、メンテナは noxfile.py 設定ファイルの RELEASE_LANGUAGES リストに言語コードを追加します。

ガイドがCIでリリース用にビルドされると、Sphinxは RELEASE_LANGUAGES リストにある言語の翻訳版のガイドも生成します。

翻訳版は英語版ガイドと同じ方法でリリースされ、言語コードにちなんだフォルダで利用できるようになります。例えば、スペイン語版は https://www.pyopensci.org/python-package-guide/es/ にあります。

よくある質問(FAQ)#

どの文字列を翻訳する必要があるか、どうすればわかりますか？#

sphinx-intl stat コマンドを実行すると、翻訳された文字列、あいまいな文字列、未翻訳の文字列を含む .po ファイルのリストが表示されます。未翻訳の文字列が最も多いファイルから、作業を始めることができます。

英語の原文で文字列が変更された場合はどうなりますか？#

If a string has changed in the original English version, it will be marked as fuzzy in the translation file the next time it is updated (update-language, update-all-languages, or update-all-release-languages). Contributors working on the translation can then review the fuzzy entries and make the necessary changes to ensure it is accurate, before removing the fuzzy tag.

翻訳されたテキスト内のリンクはどのように扱えばいいですか？#

翻訳文のリンクはそのままにしておきますが、必要に応じてリンクテキストを更新するようにしてください。例えば、英語の原文に [What is a Python package?](/tutorials/intro) へのリンクがある場合、翻訳文のリンクはそのままにして、リンクテキストを [Pythonパッケージとは何ですか](/tutorials/intro) に更新してください。

翻訳されたテキストの書式設定はどうすればよいですか？#

翻訳されたテキストの書式はそのままにして、書式タグの中のテキストも翻訳してください。たとえば、元の英語のテキストが **Test special cases:** の場合、翻訳されたテキストでは太字の書式を維持しますが、書式タグ内のテキストを **特殊ケーステスト:** に更新する必要があります。

1行では長すぎる文字列はどう扱えばいいですか？#

元の英文が長すぎて1行に収まらない場合は、複数行に分けることができます。 .po ファイル内の複数行の文字列は msgid と msgstr フィールドに空の文字列を入れ、その後に次の行のテキストの続きを入れることで示されます。例えば:

#: ../../index.md:254
msgid ""
"This is a multiple line string. The text continues on the next line."
" Notice the space in the beginning of the second line, you need to make sure"
" to account for the concatenation, there is no space inserted when starting a"
" a new line in a multiline string."
msgstr ""

画像を翻訳するにはどうすればよいですか？#

ガイド内の画像を翻訳すべきではありません。画像の翻訳版を作成するのは、追加のツールやリソースを必要とする複雑なプロセスであり、翻訳された画像がオリジナルの画像と一緒に作成されない限り、通常は行われません。多くの場合、画像の周りのテキストは、必要な翻訳を含むように修正されます。

特殊なケースでは、画像がコンテンツの理解に不可欠な場合があります。そのような場合、翻訳はこのワークフロー外のメンテナやエディタが担当します。

ガイドに掲載されていない言語への翻訳に興味があります。どうすれば始められますか？#

リストにない言語へのガイドの新しい翻訳を始めたい場合は、リポジトリに issue を作成して、あなたがその翻訳に取り組むつもりであることをメンテナに知らせてください。こうすることで、作業の重複を避け、あなたが作業を終えたときにメンテナがあなたの貢献をレビューできるようになります。

翻訳がいつリリースできるか、どうすればわかりますか？#

ガイドの次のリリースに翻訳を含める準備ができたら、メンテナは noxfile.py 設定ファイルの RELEASE_LANGUAGES リストに言語コードを追加します。これにより、リリースプロセス中に翻訳のビルドが開始され、翻訳されたバージョンのガイドがpyOpenSciのウェブサイトで利用できるようになります。

TODO：ここにはさまざまなアプローチがあります。あるプロジェクトでは、いくつかの文字列が翻訳されるとすぐに翻訳をリリースしますし、ある一定の割合のコンテンツが翻訳されるまで待つプロジェクトもあります。

翻訳を手伝ってもらうにはどうすればよいですか？#

If you have any questions or need help with your translation, you can create an issue in the Packaging Guide repository

You can also ask in the PyOpenSci Discord server (click here to join), you will find a general channel for questions related to our workflow, processes, and tools (translation-general) and channels for each of the languages we are working on (spanish-translation, japanese-translation, etc).