クイックスタート
英語の原文、日本語の翻訳、言語セレクター、コンテキストと複数形に対応したメッセージを備える小さなアプリを作成します。
1. ツールをインストールする
Python 3.11 以降を使用してください。ターミナルでプロジェクトを作成し、Python パッケージをインストールします。
mkdir localized-app
cd localized-app
python -m venv .venv
source .venv/bin/activate
python -m pip install streamlit streamlit-gettext poethepoet
これらのコマンドは Linux または macOS の Bash 用です。Windows では、仮想環境のセットアップを含め、ガイド全体を WSL 内で実行してください。poe とシェルタスクが同じ Linux 環境を使用できます。
xgettext と msgfmt を提供する GNU gettext も別途インストールします。Ubuntu や Debian では、次のコマンドを使用できます。
sudo apt-get install gettext
macOS で Homebrew を使用する場合:
brew install gettext
その他のシステムについては、GNU gettext のインストール案内をご覧ください。以降のコマンドは、仮想環境を有効にした状態で localized-app/ から実行してください。
2. 翻訳モジュールを作成する
次のコードを app.py と同じディレクトリに i18n.py として保存します。このモジュールはアプリの一部であり、ライブラリによってインストールされるものではありません。
from pathlib import Path
from streamlit_gettext import GettextWrapper
wrapper = GettextWrapper(Path(__file__).parent / "locale")
gettext = wrapper.gettext
ngettext = wrapper.ngettext
pgettext = wrapper.pgettext
npgettext = wrapper.npgettext
get_available_languages = wrapper.get_available_languages
set_preferred_languages = wrapper.set_preferred_languages
カタログのパスは i18n.py を基準にするため、作業ディレクトリに依存しません。デフォルトのドメインは messages で、messages.po と messages.mo に対応します。
3. アプリを作成する
次のコードを app.py として保存します。
import streamlit as st
from i18n import (
get_available_languages,
ngettext,
npgettext,
pgettext,
set_preferred_languages,
)
from i18n import gettext as _
language = st.selectbox(
"Language",
options=["auto", *get_available_languages()],
format_func=lambda code: "Browser language" if code == "auto" else code,
)
set_preferred_languages(None if language == "auto" else [language])
st.title(_("File manager"))
count = st.slider(_("Number of files"), 1, 30, 1)
st.write(ngettext("%(num)d file", "%(num)d files", count) % {"num": count})
st.button(pgettext("action", "Open"))
st.write(pgettext("state", "Open"))
st.write(
npgettext(
"download",
"Download %(num)d file",
"Download %(num)d files",
count,
)
% {"num": count}
)
gettext は単一のメッセージを翻訳します。ngettext は数量に応じた形式を選択します。pgettext はコンテキスト引数によって、操作としての「Open」と状態としての「Open」を区別します。npgettext はコンテキストと複数形の選択を組み合わせます。
ブラウザーの言語に従う場合は auto、手動で指定する場合は言語コードを選択します。None を渡すと、ブラウザーからの自動検出に戻ります。手動の設定は Streamlit のセッションごとに保存されます。この例の原文は英語なので、英語のカタログが存在しない場合、en は原文のメッセージを使用します。
4. メッセージを抽出して翻訳する
プロジェクトのルートに次のタスクを定義した pyproject.toml を作成するか、既存のファイルにこのセクションを追加します。
[tool.poe.tasks]
extract_pot = """
xgettext
--keyword=pgettext:1c,2
--keyword=npgettext:1c,2,3
--no-location
--output=locale/messages.pot
app.py
"""
[tool.poe.tasks.update_po]
shell = """
find locale -type f -name '*.po' -exec sh -c '
for po do
msgmerge --update --backup=none "$po" locale/messages.pot || exit
done
' sh {} +
"""
[tool.poe.tasks.compile_mo]
shell = """
find locale -type f -name '*.po' -exec sh -c '
for po do
msgfmt --check-format "$po" -o "${po%.po}.mo" || exit
done
' sh {} +
"""
[tool.poe.tasks.init_po]
shell = """
mkdir -p "locale/${language}/LC_MESSAGES" &&
msginit --input=locale/messages.pot --output-file="locale/${language}/LC_MESSAGES/messages.po" --locale="${language}" --no-translator
"""
args = [{ name = "language", positional = true, required = true }]
Poe the Poet は、このファイルに保存したコマンドを実行します。オプションを一度記述すれば、以降は短いタスク名で実行できます。GNU gettext は引き続き別途インストールする必要があります。
xgettext は拡張子 .py から Python を判別し、Python ソースの文字コードを処理します。_、gettext、ngettext はデフォルトで認識されます。コンテキスト付きの呼び出しには、追加の --keyword オプションが必要です。
抽出オプション:
| オプション | 用途 |
|---|---|
--keyword=pgettext:1c,2 |
第 1 引数はコンテキスト(c)、第 2 引数はメッセージです。 |
--keyword=npgettext:1c,2,3 |
第 1 引数はコンテキスト、第 2・第 3 引数は単数形と複数形のメッセージです。 |
--no-location |
ソースの位置情報を省略し、コード移動によるカタログの変更を減らします。 |
--output=locale/messages.pot |
共通のメッセージテンプレートをこのファイルに書き込みます。 |
app.py |
抽出対象のソースファイルです。アプリの拡張に合わせて他のファイルも追加してください。 |
init_po は言語を必須の位置引数として受け取ります。locale/<language>/LC_MESSAGES を作成し、その言語を msginit に渡します。日本語には poe init_po ja、ドイツ語には poe init_po de を実行します。言語を追加するたびにタスクを書き換える必要はありません。
update_po と compile_mo は、find で locale/ 内のすべての .po を処理します。前者はバックアップファイルを作成せずに共通テンプレートから全カタログを更新し、後者は書式プレースホルダーを検証して各 .po の隣に .mo を作成します。${po%.po} は .po の接尾辞を削除してから .mo を付けるための式です。for po do は find が渡したパスを処理し、|| exit は gettext のエラーを呼び出し元に伝えます。-exec … + では、処理の一部が失敗すると find もエラーを返すため、Poe や CI で失敗を検出できます。パスを引用符で囲むことで、空白を含むディレクトリ名にも対応します。
これらのシェルタスクには Linux と macOS で利用できる POSIX シェルと find が必要です。Windows ではガイド全体を WSL 内で実行してください。
共通のカタログディレクトリを作成し、メッセージを抽出します。
mkdir -p locale
poe extract_pot
テンプレートから .po ファイルを作成します。
poe init_po ja
このタスクは msginit を実行します。--input はテンプレート、--output-file は新しい翻訳カタログ、--locale=ja は言語を指定します。--no-translator は翻訳者情報の対話的な入力を無効にします。コマンドは翻訳が空の項目を作成し、Language や Plural-Forms を含むヘッダーを初期化します。
新しい言語ごとに poe init_po <language> を一度実行します。以降の poe update_po と poe compile_mo は、追加済みのすべての言語を一括で処理します。
翻訳の入力には、メッセージや複数形を画面上で編集できる Poedit などの専用エディターを使用できます。Crowdin や Transifex など、多くのオンライン翻訳サービスも .po をネイティブにサポートしており、別形式への変換は不要です。
これらのサービスとリポジトリを連携させることで、更新した原文を送信し、完成した翻訳を取得できます。例えば、Crowdin の GitHub 連携や Transifex の GitHub 連携を設定できます。更新された .po を取得したら poe compile_mo を実行し、新しい翻訳をアプリで利用できるようにしてください。
locale/ja/LC_MESSAGES/messages.po を開き、msgstr と msgstr[n] に翻訳を入力します。メタデータヘッダー(msgid "")の文字コードを UTF-8 に設定し、ファイルも UTF-8 で保存してください。
"Content-Type: text/plain; charset=UTF-8\n"
Plural-Forms を含む他の生成済みヘッダーフィールドはそのままにします。翻訳後の項目は次のようになります。
msgid "File manager"
msgstr "ファイルマネージャー"
msgid "Number of files"
msgstr "ファイル数"
#, python-format
msgid "%(num)d file"
msgid_plural "%(num)d files"
msgstr[0] "%(num)d個のファイル"
msgctxt "action"
msgid "Open"
msgstr "開く"
msgctxt "state"
msgid "Open"
msgstr "開いている"
#, python-format
msgctxt "download"
msgid "Download %(num)d file"
msgid_plural "Download %(num)d files"
msgstr[0] "%(num)d個のファイルをダウンロード"
.pot は抽出したテンプレート、.po は編集可能な翻訳、.mo はアプリが読み込むコンパイル済みカタログです。msgctxt は Python 呼び出しのコンテキストと一致する必要があります。%(num)d は変更せず、その言語で必要なすべての形式を翻訳してください。日本語では数量にかかわらず 1 つの形式を使用します。他の言語では、形式の数や Plural-Forms の式が異なる場合があります。
5. コンパイルして実行する
poe compile_mo
プロジェクトは次の構成になります。
localized-app/
├── app.py
├── i18n.py
├── pyproject.toml
└── locale/
├── messages.pot
└── ja/
└── LC_MESSAGES/
├── messages.po
└── messages.mo
アプリを起動します。
python -m streamlit run app.py
ja を選択すると、タイトルが「ファイルマネージャー」に変わります。スライダーを 1、2、5 に設定すると、「1個のファイル」「2個のファイル」「5個のファイル」が表示されます。ボタンには「開く」、状態には「開いている」が表示されます。en を選ぶと英語の原文に戻り、auto を選ぶとブラウザーの言語を使用します。
メッセージが英語のままの場合は、選択した言語、カタログの場所、ドメイン、および .po の編集後に .mo を再コンパイルしたかを確認してください。msgfmt は fuzzy の項目をスキップするため、翻訳を確認してフラグを削除してからコンパイルします。カタログを再コンパイルした後は Streamlit を再起動し、翻訳のキャッシュをクリアしてください。
翻訳を更新する
原文のメッセージを変更したら、再度抽出して翻訳カタログを更新します。
poe extract_pot
poe update_po
新規または変更された項目を翻訳し、fuzzy の項目を確認して poe compile_mo を実行し、アプリを再起動します。リポジトリのサンプルで使うタスクは翻訳のワークフロー、ライブラリのインターフェースは API リファレンスをご覧ください。