Skip to main content

Python i18n : le guide complet de la localisation

Configurez python-i18n avec des fichiers de traduction JSON ou YAML, gérez les paramètres de substitution et les pluriels, puis automatisez les traductions avec l'IA.

1

Installer python-i18n

python-i18n est une bibliothèque d'internationalisation légère pour Python. Elle prend en charge nativement les fichiers de traduction JSON et YAML, les clés imbriquées, l'interpolation de paramètres de substitution et la pluralisation.

Terminal
pip install python-i18n
python-i18n prend en charge JSON par défaut. Pour les fichiers de traduction YAML, installez la dépendance YAML optionnelle avec pip install python-i18n[YAML], qui ajoute PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurer les traductions

Définissez le format de fichier, ajoutez les chemins des fichiers de traduction, puis configurez vos locales par défaut et de secours. Importez cette configuration au point d'entrée de votre application, avant tout appel de traduction.

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 doit pointer vers le répertoire contenant vos fichiers de traduction, et non vers un fichier spécifique. Si les traductions renvoient les clés brutes, vérifiez que votre load_path est correct et que les noms de fichiers correspondent à vos codes de locale (par exemple en.json, de.json).
3

Créer des fichiers de traduction

Créez un fichier par langue, au format JSON ou YAML. Utilisez des clés imbriquées pour organiser les chaînes par fonctionnalité ou par page. Conservez votre langue source (généralement l'anglais) comme référence unique.

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"
  }
}
Nommez les clés selon ce qu'elles décrivent, et non selon leur emplacement : « cart.item_count » est préférable à « homepage_cart_label ». Les clés doivent survivre aux refontes de l'interface.
4

Utiliser les traductions dans votre code

Appelez i18n.t() avec un chemin de clé séparé par des points pour rechercher les chaînes traduites. Vous pouvez remplacer la locale à chaque appel, sans modifier le paramètre 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 clés imbriquées utilisent la notation par points : i18n.t('nav.home'). Si vos clés JSON contiennent des points littéraux, python-i18n les interprétera comme des séparateurs d'imbrication. Évitez les points dans les noms de clés.
5

Paramètres de substitution et pluralisation

python-i18n prend en charge l'interpolation de paramètres de substitution avec la syntaxe %{name} et une pluralisation basique via les sous-clés 'zero', 'one' et 'many'. Transmettez des arguments nommés à i18n.t() pour ces deux fonctionnalités.

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 pluralisation de python-i18n repose sur trois catégories : zero, one et many. Cela couvre l'anglais et de nombreuses langues, mais ne prend pas en charge l'intégralité des règles de pluriel CLDR (few, two, other). Pour des langues comme l'arabe, le russe ou le polonais, dont les formes de pluriel sont plus complexes, vous devrez peut-être gérer certains cas particuliers manuellement ou utiliser une bibliothèque plus avancée.
6

Changement de locale au moment de l'exécution

Changez la locale active globalement avec i18n.set('locale', code), ou remplacez-la à chaque appel via l'argument nommé locale. Dans les frameworks web, détectez la langue préférée de l'utilisateur à partir de la requête et définissez la locale avant le rendu.

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', ...) modifie la locale de manière globale. Dans les serveurs web multithreads (gunicorn avec des workers, Django), cela peut provoquer des situations de concurrence où une requête modifie la locale pendant qu'une autre est en cours de rendu. Utilisez des remplacements de locale par appel ou un stockage local au thread pour éviter ce problème.
7

Repli de locale intelligent avec python-i18n-locale-chain

Par défaut, python-i18n ne prend en charge qu'une seule locale de repli. Lorsqu'un utilisateur pt-BR n'a pas de traductions pt-BR, la bibliothèque passe directement au repli anglais, en ignorant des traductions pt-PT parfaitement valables. python-i18n-locale-chain corrige ce problème grâce à des chaînes de repli configurables couvrant 75 variantes de locale.

python-i18n-locale-chain est un package gratuit et open source. Un seul appel de fonction active 75 chaînes de repli intégrées pour les variantes régionales du chinois, du portugais, de l'espagnol, du français, de l'allemand, de l'italien, du néerlandais, de l'anglais, de l'arabe, du norvégien et du malais.
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 chaînes les plus utiles à tester : pt-BR -> pt-PT -> pt -> en (portugais), es-MX -> es-419 -> es -> en (espagnol), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (chinois traditionnel). Elles couvrent les scénarios de repli régional les plus courants.
8

Automatiser les traductions

Une fois votre configuration i18n terminée, traduisez vos fichiers de locale à l'aide de l'IA. Dans votre IDE, demandez à votre assistant IA de traduire votre fichier source, ou utilisez l'outil CLI i18n Agent dans votre 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
Traduisez de manière incrémentale. Lorsque vous ajoutez de nouvelles clés à votre fichier source, traduisez uniquement les différences plutôt que de régénérer tous les fichiers. Cela préserve les traductions révisées manuellement.

Automatiser la qualité des traductions

Détectez les clés manquantes et les espaces réservés cassés avant leur mise en production grâce à i18n-validate. Testez votre interface avec des pseudo-traductions grâce à i18n-pseudo avant l'arrivée des traductions réelles.

Pièges courants

Les traductions renvoient les clés brutes

Causes : load_path non défini ou pointant vers le mauvais répertoire, file_format ne correspondant pas à vos extensions de fichiers, ou noms de fichiers ne correspondant pas aux codes de locale. Vérifiez que i18n.load_path contient le bon répertoire et que les fichiers sont correctement nommés (par exemple, en.json, de.json).

Les fichiers YAML ne se chargent pas

python-i18n nécessite PyYAML pour la prise en charge de YAML, mais celui-ci n'est pas installé par défaut. Installez-le avec pip install python-i18n[YAML]. Sans cela, les fichiers YAML sont ignorés silencieusement et les traductions renvoient des espaces réservés de clé manquante.

Les recherches de clés imbriquées échouent

python-i18n utilise la notation par points pour les clés imbriquées : i18n.t('nav.home'). Si votre JSON utilise des clés plates avec des points dans leur nom (par exemple, 'nav.home' comme clé unique), la bibliothèque l'interprète comme une recherche imbriquée et échoue. Utilisez plutôt de véritables objets JSON imbriqués.

Les changements de locale fuient entre les requêtes

i18n.set('locale', ...) est une opération globale. Dans les serveurs multithreads, une requête peut modifier la locale pendant qu'une autre effectue son rendu. Utilisez l'argument nommé locale= sur les appels individuels à i18n.t(), ou définissez la locale dans un stockage local au thread à l'aide d'un middleware.

Structure de fichiers recommandée

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

Traduisez également :

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

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

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

Repli de locale avec python-i18n-locale-chain

Lorsqu'une clé de traduction est absente dans une locale régionale comme es-419, python-i18n passe directement à la locale par défaut au lieu de vérifier d'abord la locale parente 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

Consultez notre guide de repli de locale pour découvrir la liste complète des frameworks pris en charge et les 75 chaînes intégrées. Learn more →

Questions fréquentes