Python パッケージングガイドの翻訳ガイド#
このガイドは Python パッケージングガイドの翻訳への貢献を始めるのに役立ちます。
ガイドの翻訳に貢献するプロセスは、ガイドのソースファイルに直接取り組むのではなく、翻訳ファイルに取り組むという点を除けば、ガイドそのものに貢献するプロセスと似ています。
翻訳ステータス#
翻訳ステータス グラフは、翻訳を含む書籍が構築されるたびに更新されます。 このリンク にアクセスすると、翻訳のステータスを確認できます。
翻訳プロセスの概要#
ソフトウェアを異なる言語に適応させるプロセスは国際化、略してi18nと呼ばれます。 国際化はソースコード、私たちの場合はガイドのオリジナルの英語のソースファイルを修正することなく翻訳が行われるようにします。
Pythonパッケージガイドをビルドするために使っているドキュメントエンジンであるSphinxは、国際化をビルトインでサポートしているので、ワークフローはとても簡単です。
ガイドを実際に異なる言語に翻訳するプロセスをローカリゼーション、略してl10nと呼びます。 あなたが貢献するのはこのステップです。
ここでは、翻訳プロセスの概要を簡単に説明します:
このガイドはもともと英語で書かれており、MarkDownのファイル群に保存されています。
ソースファイルはSphinxによって処理され、各ターゲット言語のフォルダに格納された翻訳ファイルのセットを生成します。
（あなたのような!）貢献者は、これらのファイルをさまざまな言語に翻訳します。
ガイドがビルドされると、Sphinxはオリジナルの言語(英語)と、設定で定義された言語の翻訳版のガイドを作成します。
注釈
貢献するために技術的な詳細を理解する必要はありませんが、もしSphinxがどのように国際化とローカライズを処理するのかに興味があれば、 ここ に詳しい情報があります。
翻訳に貢献する2つの方法#
翻訳を投稿するには 2 つの方法があり、1 つ目の方法では、コンピューターに何もインストールする必要はありません。
GitHub Web サイトより。 翻訳ファイルはプレーンテキストであるため、ブラウザで直接編集できます。リポジトリをフォークし、フォーク内の .po ファイルを編集して、プル リクエストを開きます。初めてオープンソースに貢献する場合は、ここから始めるのが最適です。コントリビュート ガイドでは、GitHub Web サイト経由でのコントリビュート でブラウザのワークフローを説明します。フォークを取得したら、翻訳ファイルの編集 に進んでください。
コンピュータ上のローカル コピーから。 これにはさらにセットアップが必要ですが、プル リクエストを開く前に、sphinx-intl stat でファイルのどの程度が翻訳されているかを確認し、ブラウザで翻訳されたガイドをプレビューできます。大量の文字列を翻訳する予定がある場合、または作業内容をコンテキスト内で確認したい場合は、これを選択してください。
ローカル環境の設定#
これは、上記の 2 番目のアプローチを選択した場合にのみ必要です。
翻訳するための設定は、ガイドに他の何かを投稿するための設定と何ら変わりません。そのため、ここで手順を繰り返すのではなく、投稿ガイドの次のセクションを順番に実行してください。
仮想環境の作成、Windows と macOS/Linux の両方のコマンドを提供します。
注釈
開発依存関係をインストールすると、環境内で「sphinx-intl」と「nox」が使用可能になります。両方ともこのガイドの後半で使用します。「sphinx-intl」は各ファイルがどれだけ翻訳されたかを報告し、「nox」は作業をプレビューできるようにガイドを構築します。
新しい言語の翻訳を始める#
既存の翻訳に手を加える場合は、このステップを飛ばして直接次のセクションに進んでください。
重要
新しい言語へのガイドの翻訳を開始したい場合は、リポジトリに issueを作成する ことから始めてください。
新しい言語の翻訳ファイルを生成するには、conf.py 設定ファイルの languages リストにその言語を追加します。Nox はガイドとその翻訳のビルドを管理するために使うツールで、このリストを conf.py から読み込みます。
conf.py の中で languages リストを見つけて、対応する2文字のコードを追加します。例えば、フランス語への翻訳を開始したい場合は '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
このコマンドは、翻訳ファイルがまだ存在しない場合は作成し、すでに存在する場合は最新の変更内容で更新します。
翻訳ファイルは拡張子が .po のテキストファイルで、./locales 内の各言語に対応するフォルダに格納されています。例えば、スペイン語の翻訳ファイルは locales/es/LC_MESSAGES ディレクトリに格納されています。
翻訳ファイルは、元の英文テキストと翻訳テキストを対応付けるため、 "catalog" ファイルや "portable object" ファイルと呼ばれることもあります。
注釈
翻訳するためにPOフォーマットの詳細をすべて知っている必要はありません。 もっと詳しく知りたければ、 GNU gettext documentation に詳細があります。
翻訳作業#
翻訳を開始するには、翻訳したいターゲット言語に対応する ./locales 内のフォルダに移動します(例えば、スペイン語翻訳なら ./locales/es/LC_MESSAGES/ です)。
このフォルダには、ガイドの各セクションに対応する .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
このコマンドはガイドの翻訳版を1つだけビルドします:LANG に指定した言語のものです。結果は _build/html 内の、言語コードにちなんだ名前のフォルダ(例えば es)に保存されます。すべての言語を一度にビルドしたい場合は 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のウェブサイトから入手できます。
リリースのプロセス#
言語の公開準備ができたら、メンテナは conf.py 設定ファイルの release_languages リストに言語コードを追加します。
ガイドが CI でリリース用にビルドされると、Sphinx は release_languages リストにある言語の翻訳版ガイドも生成します。
翻訳版は英語版ガイドと同じ方法でリリースされ、言語コードにちなんだフォルダで利用できるようになります。例えば、スペイン語版はオンラインで公開されると https://www.pyopensci.org/python-package-guide/es/ で利用できます。
よくある質問(FAQ)#
どの文字列を翻訳する必要があるか、どうすればわかりますか？#
sphinx-intl stat コマンドを実行すると、翻訳された文字列、あいまいな文字列、未翻訳の文字列を含む .po ファイルのリストが表示されます。 未翻訳の文字列が最も多いファイルから、作業を始めることができます。
英語の原文で文字列が変更された場合はどうなりますか？#
オリジナルの英語版で文字列が変更された場合、次に翻訳ファイルが更新されるとき(update-language または update-release-languages)に fuzzy としてマークされます。翻訳に携わっているコントリビューターは、fuzzy タグを削除する前に、あいまいなエントリを確認し、正確であることを確認するために必要な変更を行うことができます。
翻訳されたテキスト内のリンクはどのように扱えばいいですか？#
翻訳文のリンクはそのままにしておきますが、必要に応じてリンクテキストを更新するようにしてください。 例えば、英語の原文に [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 を作成 して、あなたがその翻訳に取り組むつもりであることをメンテナに知らせてください。 こうすることで、作業の重複を避け、あなたが作業を終えたときにメンテナがあなたの貢献をレビューできるようになります。
翻訳がいつリリースできるか、どうすればわかりますか？#
ガイドの次のリリースに翻訳を含める準備ができたら、メンテナは conf.py 設定ファイルの release_languages リストに言語コードを追加します。これにより、リリースプロセス中に翻訳のビルドが開始され、翻訳されたバージョンのガイドが pyOpenSci のウェブサイトで利用できるようになります。
TODO：ここにはさまざまなアプローチがあります。あるプロジェクトでは、いくつかの文字列が翻訳されるとすぐに翻訳をリリースしますし、ある一定の割合のコンテンツが翻訳されるまで待つプロジェクトもあります。
翻訳を手伝ってもらうにはどうすればよいですか？#
翻訳について質問がある場合や助けが必要な場合は、 パッケージングガイドのリポジトリ に issue を作成してください。
PyOpenSci Discord サーバでも質問できます (参加は こちら) 、私たちのワークフロー、プロセス、ツールに関する一般的な質問用のチャンネル (translation-general) と、私たちが取り組んでいる各言語のチャンネル (spanish-translation、japanese-translationなど) があります。