Skip to main content

i18n en Python: guía completa de localización

Configure python-i18n con archivos JSON o YAML, gestione marcadores y plurales, y automatice después las traducciones con IA.

1

Instalar python-i18n

python-i18n es una biblioteca ligera de internacionalización para Python. Admite archivos JSON y YAML, claves anidadas, interpolación de marcadores y pluralización de serie.

Terminal
pip install python-i18n
python-i18n admite JSON de forma predeterminada. Para utilizar YAML, instale la dependencia opcional con pip install python-i18n[YAML], que añade PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurar traducciones

Defina el formato, añada las rutas de archivos y configure las regiones predeterminada y de respaldo. Importe esta configuración en el punto de entrada de la aplicación antes de llamar a ninguna traducción.

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 debe apuntar al directorio que contiene los archivos, no a uno concreto. Si devuelve claves sin procesar, compruebe que la ruta sea correcta y que los nombres coincidan con los códigos regionales —por ejemplo, en.json o de.json—.
3

Crear archivos de traducción

Cree un archivo por idioma en JSON o YAML. Utilice claves anidadas para organizar las cadenas por funcionalidad o página. Mantenga el idioma de origen —normalmente inglés— como única fuente de referencia.

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"
  }
}
Nombre las claves por lo que describen, no por el lugar donde aparecen: 'cart.item_count' es mejor que 'homepage_cart_label'. Las claves deben sobrevivir a los rediseños de la interfaz.
4

Utilizar traducciones en su código

Llame a i18n.t() con una ruta de claves separada por puntos para buscar cadenas. Puede sustituir la configuración regional en cada llamada sin cambiar el valor 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"
Las claves anidadas utilizan notación de puntos: i18n.t('nav.home'). Si sus claves JSON contienen puntos literales, python-i18n los interpretará como separadores de anidamiento. Evítelos en los nombres.
5

Marcadores y pluralización

python-i18n admite interpolación mediante la sintaxis %{name} y pluralización básica con subclaves 'zero', 'one' y 'many'. Pase argumentos de palabra clave a i18n.t() para ambas funciones.

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 pluralización de python-i18n utiliza tres categorías: zero, one y many. Abarcan inglés y muchos idiomas, pero no todas las reglas CLDR —few, two y other—. En idiomas como árabe, ruso o polaco puede necesitar gestionar casos límite a mano o emplear una biblioteca más avanzada.
6

Cambiar la configuración regional durante la ejecución

Cambie globalmente la región activa con i18n.set('locale', code) o sustitúyala por llamada mediante el argumento locale. En frameworks web, detecte el idioma preferido en la solicitud y defínalo antes de renderizar.

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', ...) cambia globalmente la región. En servidores web con varios hilos —gunicorn con workers o Django—, puede provocar condiciones de carrera: una solicitud la cambia mientras otra renderiza. Utilice sustituciones por llamada o almacenamiento local al hilo.
7

Respaldo regional inteligente con python-i18n-locale-chain

De forma predeterminada, python-i18n solo admite una configuración de respaldo. Si un usuario pt-BR no tiene traducciones pt-BR, pasa directamente al inglés y omite pt-PT. python-i18n-locale-chain lo corrige mediante cadenas configurables que cubren 75 variantes.

python-i18n-locale-chain es un paquete gratuito y de código abierto. Una llamada activa 75 cadenas integradas para variantes regionales de chino, portugués, español, francés, alemán, italiano, neerlandés, inglés, árabe, noruego y malayo.
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()
Las cadenas más útiles para probar son: pt-BR -> pt-PT -> pt -> en —portugués—, es-MX -> es-419 -> es -> en —español— y zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en —chino tradicional—. Cubren los casos regionales más habituales.
8

Automatizar traducciones

Cuando termine de configurar i18n, traduzca sus archivos de configuración regional con IA. Pida a su asistente de IA desde el IDE que traduzca el archivo de origen o utilice la CLI de i18n Agent en su proceso 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
Traduzca de forma incremental. Cuando añada claves nuevas al archivo de origen, traduzca solo las diferencias en vez de volver a generar todos los archivos. Así conserva las traducciones revisadas por personas.

Automatizar la calidad de la traducción

Detecte las claves ausentes y los marcadores rotos antes de publicar con i18n-validate. Pruebe la interfaz con pseudotraducciones mediante i18n-pseudo antes de recibir las reales.

Errores habituales

Las traducciones devuelven claves sin procesar

Causas: load_path no está definido o apunta al directorio equivocado, file_format no coincide con las extensiones o los nombres no coinciden con los códigos regionales. Compruebe que i18n.load_path contenga el directorio correcto y que los archivos se llamen, por ejemplo, en.json y de.json.

Los archivos YAML no se cargan

python-i18n necesita PyYAML para admitir YAML, pero no se instala de forma predeterminada. Instálelo con pip install python-i18n[YAML]. Sin él, los archivos se omiten silenciosamente y las traducciones devuelven marcadores de claves ausentes.

Fallan las búsquedas de claves anidadas

python-i18n utiliza notación de puntos para claves anidadas: i18n.t('nav.home'). Si el JSON usa claves planas con puntos en el nombre —por ejemplo, 'nav.home' como una sola clave—, la biblioteca lo interpreta como una búsqueda anidada y falla. Utilice objetos JSON realmente anidados.

Los cambios regionales se filtran entre solicitudes

i18n.set('locale', ...) es una operación global. En servidores con varios hilos, una solicitud puede cambiar la región mientras otra renderiza. Utilice el argumento locale= en llamadas individuales a i18n.t() o defínala en almacenamiento local al hilo mediante middleware.

Estructura de archivos recomendada

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

También puede traducir:

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

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

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Respaldo de configuraciones regionales con python-i18n-locale-chain

Cuando falta una clave en una configuración regional como es-419, python-i18n pasa directamente a la predeterminada en vez de comprobar primero la principal 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

Consulte nuestra guía de respaldo de configuraciones regionales para ver todos los frameworks admitidos y las 75 cadenas integradas. Learn more →

Preguntas frecuentes