Skip to main content

Python i18n: guia completa de localització

Configuri python-i18n amb fitxers de traducció JSON o YAML, gestioni els marcadors de posició i els plurals i, després, automatitzi les traduccions amb IA.

1

Instal·lar python-i18n

python-i18n és una biblioteca lleugera d'internacionalització per a Python. Admet de sèrie fitxers de traducció JSON i YAML, claus imbricades, interpolació de marcadors de posició i pluralització.

Terminal
pip install python-i18n
python-i18n admet JSON per defecte. Per als fitxers de traducció YAML, instal·li la dependència opcional de YAML amb pip install python-i18n[YAML], que afegeix PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurar les traduccions

Defineixi el format dels fitxers, afegeixi els camins dels fitxers de traducció i configuri la configuració regional predeterminada i l’alternativa. Importi aquesta configuració al punt d'entrada de l'aplicació abans de fer cap crida de traducció.

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 ha d'apuntar al directori que conté els fitxers de traducció, no pas a un fitxer concret. Si les traduccions retornen les claus sense processar, comprovi que load_path sigui correcte i que els noms dels fitxers coincideixin amb els codis de configuració regional (p. ex., en.json, de.json).
3

Crear els fitxers de traducció

Creï un fitxer per llengua en format JSON o YAML. Faci servir claus imbricades per organitzar les cadenes per funcionalitat o pàgina. Mantingui la llengua d'origen, habitualment l'anglès, com a única font de referència.

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"
  }
}
Anomeni les claus segons allò que descriuen, no segons on apareixen: 'cart.item_count' és millor que 'homepage_cart_label'. Les claus han de continuar sent vàlides després dels redissenys de la interfície.
4

Utilitzar les traduccions al codi

Cridi i18n.t() amb un camí de claus separades per punts per cercar cadenes traduïdes. Pot substituir la configuració regional en cada crida sense canviar la configuració global.

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"
Les claus imbricades utilitzen la notació amb punts: i18n.t('nav.home'). Si les claus JSON contenen punts literals, python-i18n els interpretarà com a separadors d'imbricació. Eviti els punts als noms de les claus.
5

Marcadors de posició i pluralització

python-i18n admet la interpolació de marcadors de posició amb la sintaxi %{name} i la pluralització bàsica mitjançant les subclaus 'zero', 'one' i 'many'. Passi arguments amb nom a i18n.t() per utilitzar totes dues funcions.

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"
La pluralització de python-i18n utilitza tres categories: zero, one i many. Això cobreix l'anglès i moltes altres llengües, però no admet totes les regles de plural de CLDR (few, two, other). En llengües com l'àrab, el rus o el polonès, que tenen formes plurals complexes, és possible que hagi de gestionar manualment els casos límit o utilitzar una biblioteca més avançada.
6

Canviar la configuració regional en temps d'execució

Canviï globalment la configuració regional activa amb i18n.set('locale', code) o substitueixi-la en cada crida mitjançant l'argument amb nom locale. Als entorns de treball web, detecti la llengua preferida de l'usuari a partir de la sol·licitud i defineixi la configuració regional abans de renderitzar.

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', ...) canvia globalment la configuració regional. Als servidors web multifil (gunicorn amb workers, Django), això pot provocar condicions de cursa en què una sol·licitud canviï la configuració regional mentre se n'està renderitzant una altra. Per evitar-ho, substitueixi la configuració regional en cada crida o utilitzi emmagatzematge local del fil.
7

Selecció intel·ligent de configuracions regionals alternatives amb python-i18n-locale-chain

Per defecte, python-i18n només admet una configuració regional alternativa. Quan no hi ha traduccions pt-BR per a un usuari pt-BR, la biblioteca passa directament a l'anglès alternatiu i ignora les traduccions pt-PT perfectament vàlides. python-i18n-locale-chain ho resol amb cadenes alternatives configurables que cobreixen 75 variants de configuració regional.

python-i18n-locale-chain és un paquet gratuït i de codi obert. Una sola crida de funció activa 75 cadenes alternatives integrades per a variants regionals del xinès, el portuguès, l'espanyol, el francès, l'alemany, l'italià, el neerlandès, l'anglès, l'àrab, el noruec i el malai.
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()
Les cadenes més importants que convé provar són: pt-BR -> pt-PT -> pt -> en (portuguès), es-MX -> es-419 -> es -> en (espanyol) i zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (xinès tradicional). Cobreixen els casos més habituals de selecció de variants regionals alternatives.
8

Automatitzar les traduccions

Un cop completada la configuració d'i18n, tradueixi els fitxers de configuració regional mitjançant IA. A l'IDE, demani a l'assistent d'IA que tradueixi el fitxer d'origen o utilitzi la CLI d'i18n Agent a la canalització de CI/CD.

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
Tradueixi de manera incremental. Quan afegeixi claus noves al fitxer d'origen, tradueixi només les diferències en lloc de tornar a generar tots els fitxers. Així es conserven les traduccions revisades per persones.

Automatitzar la qualitat de les traduccions

Detecti amb i18n-validate les claus que falten i els marcadors de posició malmesos abans que arribin a producció. Provi la interfície amb pseudotraduccions mitjançant i18n-pseudo abans que arribin les traduccions reals.

Errors habituals

Les traduccions retornen les claus sense processar

Causes: load_path no està definit o apunta al directori equivocat, file_format no coincideix amb les extensions dels fitxers o els noms dels fitxers no coincideixen amb els codis de configuració regional. Verifiqui que i18n.load_path contingui el directori correcte i que els fitxers tinguin els noms adequats (p. ex., en.json, de.json).

Els fitxers YAML no es carreguen

python-i18n requereix PyYAML per admetre YAML, però no s'instal·la per defecte. Instal·li’l amb pip install python-i18n[YAML]. Sense aquest paquet, els fitxers YAML s'ignoren silenciosament i les traduccions retornen marcadors de posició de claus absents.

Les cerques de claus imbricades fallen

python-i18n utilitza la notació amb punts per a les claus imbricades: i18n.t('nav.home'). Si el JSON utilitza claus planes amb punts al nom (p. ex., 'nav.home' com una sola clau), la biblioteca les interpreta com una cerca imbricada i falla. Utilitzi objectes JSON realment imbricats.

Els canvis de configuració regional es filtren entre sol·licituds

i18n.set('locale', ...) és una operació global. Als servidors multifil, una sol·licitud pot canviar la configuració regional mentre se'n renderitza una altra. Utilitzi l'argument amb nom locale= en cada crida d'i18n.t() o defineixi la configuració regional en emmagatzematge local del fil mitjançant un middleware.

Estructura de fitxers recomanada

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
└── ...

Traduir també:

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

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

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Configuracions regionals alternatives amb python-i18n-locale-chain

Quan falta una clau de traducció en una configuració regional com es-419, python-i18n passa directament a la configuració regional predeterminada en lloc de comprovar primer la configuració regional superior 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

Consulti la guia de configuracions regionals de reserva per veure la llista completa de frameworks compatibles i les 75 cadenes integrades. Learn more →

Preguntes freqüents