Skip to main content

Python i18n：ローカライズ完全ガイド

JSON または YAML 翻訳ファイルを使用して python-i18n を設定し、プレースホルダーと複数形を処理してから、AI で翻訳を自動化します。

1

python-i18n のインストール

python-i18n は、Python 向けの軽量な国際化ライブラリです。JSON と YAML の翻訳ファイル、ネストしたキー、プレースホルダーの補間、複数形に標準で対応しています。

Terminal
pip install python-i18n
python-i18n はデフォルトで JSON に対応しています。YAML 翻訳ファイルを使用するには、pip install python-i18n[YAML] でオプションの YAML 依存関係をインストールします。これにより PyYAML が追加されます。
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

翻訳の設定

ファイル形式を設定し、翻訳ファイルのパスを追加して、デフォルトロケールとフォールバックロケールを指定します。翻訳関数を呼び出す前に、アプリケーションのエントリーポイントでこの設定を import してください。

i18n_config.py
import i18n

# Set the file format (json or yaml)
i18n.set("file_format", "json")

# Add the directory containing your translation files
i18n.load_path.append("translations/")

# Set the default locale
i18n.set("locale", "en")

# Set the fallback locale (used when a key is missing)
i18n.set("fallback", "en")

# Enable/disable error on missing translations
i18n.set("error_on_missing_translation", False)
load_path は、特定のファイルではなく翻訳ファイルを含むディレクトリを指す必要があります。翻訳で未変換のキーが返される場合は、load_path が正しいことと、ファイル名がロケールコード（例：en.json、de.json）と一致することを確認してください。
3

翻訳ファイルの作成

JSON または YAML 形式で言語ごとのファイルを 1 つ作成します。ネストしたキーを使用し、機能またはページ別に文字列を整理してください。ソース言語（通常は英語）を唯一の信頼できる情報源として維持します。

translations/en.json
// translations/en.json
{
  "greeting": "Hello!",
  "welcome": "Welcome to our application",
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "cart": {
    "item_count": "%{count} item(s) in your cart"
  }
}

// translations/de.json
{
  "greeting": "Hallo!",
  "welcome": "Willkommen in unserer Anwendung",
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "cart": {
    "item_count": "%{count} Artikel in Ihrem Warenkorb"
  }
}
キー名は表示場所ではなく、内容に基づいて付けてください。「homepage_cart_label」より「cart.item_count」が適切です。UI を再設計しても維持できるキーにします。
4

コードでの翻訳の使用

ドット区切りのキーパスを指定して i18n.t() を呼び出し、翻訳文字列を検索します。グローバル設定を変えず、呼び出しごとにロケールを上書きできます。

app.py
import i18n

# Simple translation
print(i18n.t("greeting"))          # "Hello!"
print(i18n.t("nav.home"))          # "Home"
print(i18n.t("nav.about"))         # "About"

# Translation with a specific locale
print(i18n.t("greeting", locale="de"))   # "Hallo!"
print(i18n.t("nav.home", locale="ja"))   # "ホーム"

# Missing key returns a placeholder
print(i18n.t("missing.key"))       # "Missing.Key"
ネストしたキーにはドット表記を使用します：i18n.t('nav.home')。JSON キー自体にドットが含まれる場合、python-i18n はネストの区切りとして解釈します。キー名にドットを使用しないでください。
5

プレースホルダーと複数形

python-i18n は、%{name} 構文によるプレースホルダーの補間と、「zero」「one」「many」サブキーによる基本的な複数形に対応しています。どちらの機能にも、i18n.t() へキーワード引数を渡します。

Placeholders
# translations/en.json
# {
#   "welcome_user": "Welcome, %{name}!",
#   "order_status": "Order #%{order_id}: %{status}",
#   "file_size": "File size: %{size} %{unit}"
# }

import i18n

# Single placeholder
print(i18n.t("welcome_user", name="Alice"))
# "Welcome, Alice!"

# Multiple placeholders
print(i18n.t("order_status", order_id=12345, status="shipped"))
# "Order #12345: shipped"

# Reusable with different values
print(i18n.t("file_size", size=2.5, unit="MB"))
# "File size: 2.5 MB"

print(i18n.t("file_size", size=800, unit="KB"))
# "File size: 800 KB"
Pluralization
# translations/en.json
# {
#   "inbox": {
#     "zero": "No messages",
#     "one": "1 message",
#     "many": "%{count} messages"
#   }
# }

import i18n

print(i18n.t("inbox", count=0))    # "No messages"
print(i18n.t("inbox", count=1))    # "1 message"
print(i18n.t("inbox", count=42))   # "42 messages"
python-i18n の複数形は、zero、one、many の 3 カテゴリーを使用します。英語など多くの言語に対応できますが、CLDR の全複数形規則（few、two、other）には対応していません。アラビア語、ロシア語、ポーランド語のように複雑な複数形を持つ言語では、特殊なケースを手動で処理するか、より高度なライブラリが必要です。
6

実行時のロケール切り替え

i18n.set('locale', code) で有効なロケールをグローバルに切り替えるか、locale キーワード引数で呼び出しごとに上書きします。Web フレームワークではリクエストからユーザーの優先言語を検出し、レンダリング前にロケールを設定してください。

Locale switching
import i18n

# Set locale globally
i18n.set("locale", "de")
print(i18n.t("greeting"))           # "Hallo!"

# Switch to Japanese
i18n.set("locale", "ja")
print(i18n.t("greeting"))           # "こんにちは！"

# Override per-call without changing global locale
i18n.set("locale", "en")
print(i18n.t("greeting"))           # "Hello!"
print(i18n.t("greeting", locale="de"))  # "Hallo!"
app.py
from flask import Flask, request, g
import i18n

app = Flask(__name__)

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

SUPPORTED_LOCALES = ["en", "de", "ja", "es", "fr"]

@app.before_request
def set_locale():
    # Check URL parameter, cookie, then Accept-Language header
    locale = request.args.get("lang")
    if not locale:
        locale = request.cookies.get("locale")
    if not locale:
        locale = request.accept_languages.best_match(SUPPORTED_LOCALES)
    g.locale = locale or "en"
    i18n.set("locale", g.locale)

@app.route("/")
def index():
    return i18n.t("welcome")
i18n.set('locale', ...) はロケールをグローバルに変更します。マルチスレッド Web サーバー（ワーカーを使用する gunicorn、Django）では、あるリクエストのレンダリング中に別のリクエストがロケールを変える競合状態が発生する可能性があります。呼び出しごとのロケール上書きまたはスレッドローカルストレージを使用して回避してください。
7

python-i18n-locale-chain による高度なロケールフォールバック

python-i18n はデフォルトで、単一のフォールバックロケールにしか対応していません。pt-BR の翻訳がない場合、適切な pt-PT 翻訳を無視して英語へ直接フォールバックします。python-i18n-locale-chain は、75 のロケールバリエーションを網羅する設定可能なフォールバックチェーンで、この問題を修正します。

python-i18n-locale-chain は、無料のオープンソースパッケージです。関数を 1 回呼び出すだけで、中国語、ポルトガル語、スペイン語、フランス語、ドイツ語、イタリア語、オランダ語、英語、アラビア語、ノルウェー語、マレー語の地域バリエーション向けに、75 の組み込みフォールバックチェーンを有効化できます。
Terminal
pip install python-i18n-locale-chain
i18n_config.py
from locale_chain import configure
import i18n

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

# Activate smart fallback chains (75 built-in chains)
configure()

# Now pt-BR falls back to pt-PT -> pt -> en (instead of just en)
result = i18n.t("greeting", locale="pt-BR")

# es-MX falls back to es-419 -> es -> en
result = i18n.t("greeting", locale="es-MX")

# zh-Hant-HK falls back to zh-Hant-TW -> zh-Hant -> en
result = i18n.t("greeting", locale="zh-Hant-HK")
Advanced configuration
from locale_chain import configure, reset

# Override specific chains
configure(overrides={
    "pt-BR": ["pt"],         # Skip pt-PT, go straight to pt
    "ja-JP": ["ja"],         # Add a new chain
})

# Full custom map (no defaults)
configure(
    fallbacks={"pt-BR": ["pt-PT"]},
    merge_defaults=False
)

# Use German as final fallback instead of English
configure(default_locale="de")

# Restore original i18n.t() behaviour
reset()
特に重要なチェーンとして、ポルトガル語の pt-BR -> pt-PT -> pt -> en、スペイン語の es-MX -> es-419 -> es -> en、繁体字中国語の zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en をテストしてください。最も一般的な地域フォールバックのケースを網羅できます。
8

翻訳の自動化

i18n の設定が完了したら、AI を使用してロケールファイルを翻訳します。IDE で AI アシスタントにソースファイルの翻訳を依頼するか、CI/CD パイプラインで i18n Agent CLI を使用できます。

Terminal
# In your IDE, ask your AI assistant:
> Translate translations/en.json to German, Japanese, and Spanish

translations/de.json created (1.2s)
translations/ja.json created (1.5s)
translations/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate translations/en.json --lang de,ja,es
差分単位で翻訳してください。ソースファイルに新しいキーを追加した場合は、すべてのファイルを再生成せず、差分だけを翻訳します。人が確認済みの翻訳を保持できます。

翻訳品質の自動管理

i18n-validate を使用すると、リリース前に欠落キーや壊れたプレースホルダーを検出できます。実際の翻訳が届く前に、i18n-pseudo の疑似翻訳で UI をテストしてください。

よくある問題

翻訳が未変換のキーを返す

原因として、load_path が未設定または誤ったディレクトリを指していること、file_format がファイル拡張子と一致しないこと、ファイル名がロケールコードと一致しないことが考えられます。i18n.load_path に正しいディレクトリが含まれ、ファイル名（例：en.json、de.json）が正しいことを確認してください。

YAML ファイルを読み込めない

python-i18n で YAML を使用するには PyYAML が必要ですが、デフォルトではインストールされません。pip install python-i18n[YAML] でインストールしてください。インストールしない場合、YAML ファイルは通知なしで無視され、翻訳では欠落キープレースホルダーが返されます。

ネストしたキーを検索できない

python-i18n はネストしたキーにドット表記を使用します：i18n.t('nav.home')。JSON で名前にドットを含むフラットキー（単一キーとしての「nav.home」など）を使用すると、ライブラリはネストした検索と解釈して失敗します。代わりに、実際にネストした JSON オブジェクトを使用してください。

リクエスト間でロケール変更が混在する

i18n.set('locale', ...) はグローバル操作です。マルチスレッドサーバーでは、あるリクエストのレンダリング中に別のリクエストがロケールを変更する可能性があります。個別の i18n.t() 呼び出しに locale= キーワード引数を使用するか、ミドルウェアでスレッドローカルストレージにロケールを設定してください。

推奨ファイル構成

Project Structure
my-python-app/
├── translations/
│   ├── en.json           # Source language (JSON)
│   ├── de.json           # German
│   ├── ja.json           # Japanese
│   ├── es.json           # Spanish
│   └── pt-BR.json        # Brazilian Portuguese
├── app.py                # Application entry point
├── i18n_config.py        # i18n setup and configuration
├── requirements.txt      # pip dependencies
└── pyproject.toml        # Project metadata

# Or with YAML files:
my-python-app/
├── translations/
│   ├── en.yml
│   ├── de.yml
│   └── ja.yml
├── app.py
└── ...

ほかの翻訳対象：

i18n Agent を今すぐ試す

翻訳ファイルをここにドロップ

JSON, YAML, PO, XML, CSV, Markdown, Properties

またはクリックしてファイルを選択

翻訳先言語

登録不要すぐに見積もり

python-i18n-locale-chain によるロケールフォールバック

es-419 のような地域ロケールに翻訳キーがない場合、python-i18n は親ロケール es を先に確認せず、デフォルトロケールへ直接フォールバックします。

Terminal
pip install python-i18n-locale-chain
Configuration
from i18n_locale_chain import configure_chain

configure_chain('{')
    'es': ['en', 'ru'],
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
'}')

# Usage: t('greeting', locale='es') — falls back through chain

対応フレームワークの全一覧と 75 の組み込みチェーンについては、ロケールフォールバックガイドをご覧ください。 Learn more →

よくある質問