Skip to main content

i18n di Python: la guida completa alla localizzazione

Configuri python-i18n con file di traduzione JSON o YAML, gestisca segnaposto e plurali, quindi automatizzi le traduzioni con l'IA.

1

Installare python-i18n

python-i18n è una biblioteca di internazionalizzazione leggera per Python. Supporta file di traduzione JSON e YAML, chiavi annidate, interpolazione dei segnaposto e gestione dei plurali senza configurazione aggiuntiva.

Terminal
pip install python-i18n
python-i18n supporta JSON per impostazione predefinita. Per i file di traduzione YAML, installi la dipendenza YAML facoltativa con pip install python-i18n[YAML], che aggiunge PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurare le traduzioni

Imposti il formato dei file, aggiunga i percorsi dei file di traduzione e configuri le lingue predefinita e di fallback. Importi questa configurazione nel punto di ingresso dell'applicazione prima di qualsiasi chiamata di traduzione.

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 deve indicare la directory che contiene i file di traduzione, non un file specifico. Se le traduzioni restituiscono chiavi non elaborate, controlli che load_path sia corretto e che i nomi dei file corrispondano ai codici delle lingue (ad esempio, en.json, de.json).
3

Creare i file di traduzione

Crei un file per ogni lingua in formato JSON o YAML. Usi chiavi annidate per organizzare le stringhe per funzionalità o pagina. Mantenga la lingua di origine, generalmente l'inglese, come unica fonte di riferimento.

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"
  }
}
Assegni alle chiavi nomi che descrivono il contenuto, non la posizione: 'cart.item_count' è preferibile a 'homepage_cart_label'. Le chiavi devono sopravvivere alle riprogettazioni dell'interfaccia.
4

Usare le traduzioni nel codice

Chiami i18n.t() con un percorso della chiave separato da punti per cercare le stringhe tradotte. Può sostituire la lingua per ogni chiamata senza cambiare l'impostazione globale.

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"
Le chiavi annidate usano la notazione puntata: i18n.t('nav.home'). Se le chiavi JSON contengono punti letterali, python-i18n li interpreterà come separatori di annidamento. Eviti i punti nei nomi delle chiavi.
5

Segnaposto e gestione dei plurali

python-i18n supporta l'interpolazione dei segnaposto con la sintassi %{name} e una gestione di base dei plurali tramite le sottochiavi 'zero', 'one' e 'many'. Passi argomenti con parola chiave a i18n.t() per entrambe le funzionalità.

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 gestione dei plurali di python-i18n usa tre categorie: zero, one e many. Copre l'inglese e molte altre lingue, ma non supporta tutte le regole del plurale CLDR (few, two, other). Per lingue con forme plurali complesse, come arabo, russo o polacco, potrebbe dover gestire manualmente i casi limite oppure usare una biblioteca più avanzata.
6

Cambio di lingua durante l'esecuzione

Cambi la lingua attiva a livello globale con i18n.set('locale', code) oppure la sostituisca per singola chiamata con l'argomento con parola chiave locale. Nei framework web, rilevi dalla richiesta la lingua preferita dall'utente e la imposti prima del rendering.

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 la lingua a livello globale. Nei server web multithread, come gunicorn con worker o Django, può causare race condition in cui una richiesta cambia la lingua mentre è in corso il rendering di un'altra. Usi sostituzioni della lingua per singola chiamata o un archivio locale del thread per evitare il problema.
7

Fallback intelligente con python-i18n-locale-chain

Per impostazione predefinita, python-i18n supporta una sola lingua di fallback. Quando un utente pt-BR non dispone di traduzioni pt-BR, la biblioteca passa direttamente al fallback inglese, ignorando traduzioni pt-PT perfettamente valide. python-i18n-locale-chain risolve il problema con catene di fallback configurabili che coprono 75 varianti linguistiche.

python-i18n-locale-chain è un pacchetto open source gratuito. Una sola chiamata di funzione attiva 75 catene di fallback integrate per le varianti regionali di cinese, portoghese, spagnolo, francese, tedesco, italiano, olandese, inglese, arabo, norvegese e malese.
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()
Le catene più importanti da testare: pt-BR → pt-PT → pt → en (portoghese), es-MX → es-419 → es → en (spagnolo), zh-Hant-HK → zh-Hant-TW → zh-Hant → en (cinese tradizionale). Coprono gli scenari di fallback regionale più comuni.
8

Automatizzare le traduzioni

Completata la configurazione i18n, tradurre i file con l'IA. Chiedere all'assistente nell'IDE o usare i18n Agent CLI nella pipeline 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
Traduca in modo incrementale. Quando aggiunge nuove chiavi al file di origine, traduca soltanto il diff anziché rigenerare tutti i file. In questo modo preserva le traduzioni revisionate da persone.

Automatizzare la qualità

Con i18n-validate, rilevi chiavi mancanti e segnaposto non validi prima del rilascio. Testi l'interfaccia con le pseudotraduzioni di i18n-pseudo prima che arrivino le traduzioni reali.

Problemi comuni

Le traduzioni restituiscono chiavi non elaborate

Cause: load_path non impostato o indirizzato alla directory errata, file_format non corrispondente alle estensioni dei file oppure nomi dei file non corrispondenti ai codici delle lingue. Verifichi che i18n.load_path contenga la directory corretta e che i file siano denominati correttamente (ad esempio, en.json, de.json).

I file YAML non vengono caricati

python-i18n richiede PyYAML per il supporto YAML, ma non viene installato per impostazione predefinita. Lo installi con pip install python-i18n[YAML]. Senza questa dipendenza, i file YAML vengono ignorati senza segnalazioni e le traduzioni restituiscono segnaposto per le chiavi mancanti.

La ricerca delle chiavi annidate non riesce

python-i18n usa la notazione puntata per le chiavi annidate: i18n.t('nav.home'). Se il JSON usa chiavi semplici con punti nel nome, ad esempio 'nav.home' come chiave unica, la biblioteca interpreta il punto come una ricerca annidata e non riesce. Usi invece oggetti JSON effettivamente annidati.

I cambi di lingua interferiscono tra le richieste

i18n.set('locale', ...) è un'operazione globale. Nei server multithread, una richiesta può cambiare la lingua mentre è in corso il rendering di un'altra. Usi l'argomento con parola chiave locale= nelle singole chiamate i18n.t() oppure imposti la lingua in un archivio locale del thread tramite un middleware.

Struttura dei file consigliata

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

Traduca anche:

Provi subito i18n Agent

Trascinare qui il file di traduzione

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

oppure fare clic per selezionarlo

Lingue di destinazione

Nessuna registrazione richiestaPreventivo immediato

Fallback della lingua con python-i18n-locale-chain

Quando manca una chiave di traduzione in una lingua regionale come es-419, python-i18n passa direttamente alla lingua predefinita anziché controllare prima la lingua principale 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

Consultare la Guida al fallback delle lingue per l'elenco completo dei framework supportati e delle 75 catene integrate. Learn more →

Domande frequenti