Python パッケージングガイドの翻訳ガイド#
このガイドは Python パッケージングガイドの翻訳への貢献を始めるのに役立ちます。
ガイドの翻訳に貢献するプロセスは、ガイドのソースファイルに直接取り組むのではなく、翻訳ファイルに取り組むという点を除けば、ガイドそのものに貢献するプロセスと似ています。
翻訳ステータス#
The translation status graph updates every time the book is build with translations. You can see the status of the translations by going to this link
翻訳プロセスの概要#
ソフトウェアを異なる言語に適応させるプロセスは国際化、略してi18nと呼ばれます。 国際化はソースコード、私たちの場合はガイドのオリジナルの英語のソースファイルを修正することなく翻訳が行われるようにします。
Pythonパッケージガイドをビルドするために使っているドキュメントエンジンであるSphinxは、国際化をビルトインでサポートしているので、ワークフローはとても簡単です。
ガイドを実際に異なる言語に翻訳するプロセスをローカリゼーション、略してl10nと呼びます。 あなたが貢献するのはこのステップです。
ここでは、翻訳プロセスの概要を簡単に説明します:
このガイドはもともと英語で書かれており、MarkDownのファイル群に保存されています。
ソースファイルはSphinxによって処理され、各ターゲット言語のフォルダに格納された翻訳ファイルのセットを生成します。
（あなたのような!）貢献者は、これらのファイルをさまざまな言語に翻訳します。
ガイドがビルドされると、Sphinxはオリジナルの言語(英語)と、設定で定義された言語の翻訳版のガイドを作成します。
注釈
貢献するために技術的な詳細を理解する必要はありませんが、もしSphinxがどのように国際化とローカライズを処理するのかに興味があれば、 ここ に詳しい情報があります。
Two Ways to Contribute a Translation#
There are two ways to contribute a translation, and the first one does not require you to install anything on your computer.
From the GitHub website. Translation files are plain text, so you can edit them right in your browser. Fork the repository, edit a .po file in your fork, and open a pull request. This is the best place to start if this is your first open source contribution. The contributing guide walks through the browser workflow in Contributing via the GitHub website. Once you have a fork, you can skip ahead to Editing the Translation Files.
From a local copy on your computer. This takes more setup, but it lets you check how much of a file is translated with sphinx-intl stat and preview the translated guide in your browser before you open a pull request. Choose this if you plan to translate a lot of strings or want to see your work in context.
ローカル環境の設定#
You only need this if you chose the second approach above.
Setting up to translate is no different from setting up to contribute anything else to the guide, so rather than repeat the steps here, follow these sections of the contributing guide in order:
Create a virtual environment, which gives the commands for both Windows and macOS/Linux
注釈
Installing the development dependencies is what makes sphinx-intl and nox available in your environment. Both are used later in this guide: sphinx-intl reports how much of each file has been translated, and nox builds the guide so you can preview your work.
新しい言語の翻訳を始める#
既存の翻訳に手を加える場合は、このステップを飛ばして直接次のセクションに進んでください。
重要
新しい言語へのガイドの翻訳を開始したい場合は、リポジトリに issueを作成する ことから始めてください。
To generate the translation files for a new language, add the language to the languages list in the conf.py configuration file. Nox is the tool we use to manage the building of the guide and its translations, and it reads this list from conf.py.
Inside conf.py, find the languages list and add the corresponding two-letter code. For example, if you want to start the translation of the guide into French, you would add 'fr':
# all languages that have .po files generated for them
# (excluding english)
languages = ["es", "ja", "pt", "fr"]
注釈
ここで 、2文字のSphinx言語オプションのリストを見つけることができます。
翻訳ファイルの準備#
翻訳ファイルには、英語の原文と翻訳文を入力するスペースが含まれています。 翻訳を始める前に、翻訳ファイルがガイドの最新の変更に対応していることを確認する必要があります。
以下のコマンドを実行し、LANGを作業する予定の言語コードに置き換えてください (例えばスペイン語は es):
nox -s update-language -- LANG
このコマンドは、翻訳ファイルがまだ存在しない場合は作成し、すでに存在する場合は最新の変更内容で更新します。
The translation files are text files with the .po extension stored in ./locales, in folders corresponding to each language. For example, the translation files for Spanish are stored in the locales/es/LC_MESSAGES directory.
翻訳ファイルは、元の英文テキストと翻訳テキストを対応付けるため、 "catalog" ファイルや "portable object" ファイルと呼ばれることもあります。
注釈
翻訳するためにPOフォーマットの詳細をすべて知っている必要はありません。 もっと詳しく知りたければ、 GNU gettext documentation に詳細があります。
翻訳作業#
In order to start translating, go to the folder inside ./locales corresponding to the target language you want to translate to (for example, ./locales/es/LC_MESSAGES/ for the Spanish translation).
このフォルダには、ガイドの各セクションに対応する .po ファイルのセットがあります：
$ cd ./locales/es/LC_MESSAGES/
$ ls *.po
continuous-integration.po
CONTRIBUTING.po
documentation.po
index.po
maintain-automate.po
package-structure-code.po
tests.po
TRANSLATING.po
tutorials.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行目から探してください）を修正し、別途プルリクエストを提出してください。
翻訳されたドキュメントの構築#
翻訳が終わったら、あるいは文脈の中で翻訳をチェックしたい場合は、次のコマンドを使用して、ガイドをコンピュータにローカルに構築することができます、 LANGを適切な言語コードに置き換えます (例: スペイン語なら es )。
nox -s build-language -- LANG
This command builds a single translated version of the guide: the one for LANG. The result is stored in _build/html, in a folder named after the language code (e.g., es). If you want to build every language at once instead, use nox -s build-all-languages.
ブラウザで翻訳版のガイドを見るには、対応する index.html ファイルを開いてください。 例えば、スペイン語の翻訳版を見るには、 _build/html/es/index.html を開きます。
また、翻訳ファイルを変更すると自動的に更新されるガイドのライブバージョンをビルドすることもできます。 これを行うには、nox -s docs-live-lang コマンドを使用します。 この場合、ビルドしたい言語を指定する必要があることに注意してください。 例えば、スペイン語翻訳に取り組んでいる場合、次のように実行します:
nox -s docs-live-lang -- es
言語コードの前の -- に注意してください。これは次の引数がnoxセッションに渡され、noxによって直接解釈されないことを示します。 もし -- を忘れると、noxは代わりに 'es' という名前のセッションを探し、それが存在しないとエラーを発生させます。
このコマンドは 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: このタグ付けは、GitHub Actionsで自動化できるかもしれません。
PRを提出する際には、あなたが行った変更についての簡単な説明と、レビュアーにとって参考になりそうな文脈（新しい文字列を翻訳した、あいまいなエントリーを見直した、誤字脱字を修正した、など）を必ず含めてください。
レビュープロセス#
翻訳貢献のレビュープロセスは、ガイドへの他のレビューのレビュープロセスと同様です。
TODO: このセクションは、私たちが採用するレビューのワークフローによって、もっと作業が必要です。 他のプロジェクトでは、通常、言語ごとにコーディネーター/編集者を割り当て、その人が翻訳投稿のレビューとマージに責任を持ちます。
各言語には担当エディターがおり、翻訳投稿の確認と統合を担当します。 エディターは、変更が正確で、ガイドのスタイルやトーンと一致していることを確認します。
エディターが翻訳を改善するために説明を求めたり、変更を提案したりすることがあります。 このような場合は、要求された変更を行い、元のPRを投稿したブランチにプッシュしてください。
エディターが翻訳に満足したら、PRをマージします。ガイドの翻訳版は言語がリリースされ次第、pyOpenSciのウェブサイトから入手できます。
リリースのプロセス#
If a language is ready to go live, the maintainers will add the language code to the release_languages list in the conf.py configuration file.
When the guide is built for release in CI, Sphinx will also generate the translated versions of the guide for the languages in the release_languages list.
Translations are released in the same way as the English version of the guide, and the translated versions will be available in folders named after the language code. For example, the Spanish translation will be available at: https://www.pyopensci.org/python-package-guide/es/ when it is published online.
よくある質問(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 or update-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 を作成 して、あなたがその翻訳に取り組むつもりであることをメンテナに知らせてください。 こうすることで、作業の重複を避け、あなたが作業を終えたときにメンテナがあなたの貢献をレビューできるようになります。
翻訳がいつリリースできるか、どうすればわかりますか？#
When a translation is ready to be included in the next release of the guide, the maintainers will add the language code to the release_languages list in the conf.py configuration file. This will trigger the build of the translation during the release process, and the translated version of the guide will be available on the pyOpenSci website.
TODO：ここにはさまざまなアプローチがあります。あるプロジェクトでは、いくつかの文字列が翻訳されるとすぐに翻訳をリリースしますし、ある一定の割合のコンテンツが翻訳されるまで待つプロジェクトもあります。
翻訳を手伝ってもらうにはどうすればよいですか？#
翻訳について質問がある場合や助けが必要な場合は、 パッケージングガイドのリポジトリ に issue を作成してください。
PyOpenSci Discord サーバでも質問できます (参加は こちら) 、私たちのワークフロー、プロセス、ツールに関する一般的な質問用のチャンネル (translation-general) と、私たちが取り組んでいる各言語のチャンネル (spanish-translation、japanese-translationなど) があります。