← Blog

Comment traduire un projet Django : makemessages, fichiers .po et traduction automatique

Traduisez les fichiers .po de votre projet Django en anglais, portugais et français avec python manage.py translate : extrait, traduit, écrit et compile. Avec la sortie réelle.

· 2 min de lectura

Traduire un projet Django se fait généralement ainsi : makemessages, ouvrir chaque .po, copier les msgid dans un traducteur ou dans ChatGPT, coller les msgstr un par un, prier pour qu'aucun %(name)s ne se casse et lancer compilemessages. Et recommencer avec chaque nouveau texte.

Ici, on fait tout avec une seule commande, python manage.py translate, en utilisant le paquet translate-projects-django. Tout ce que vous voyez ci-dessous (terminal et fichiers .po) est la sortie réelle d'une exécution sur un projet de test.

De quoi avez-vous besoin

  • Python 3.8 ou supérieur et Django 3.2 ou supérieur.
  • GNU gettext (xgettext et msgfmt), comme pour toute traduction dans Django : sudo apt-get install gettext ou brew install gettext.
  • Un compte gratuit Translate Projects avec un projet et son API token (Premiers pas).
  • La clé API de votre fournisseur d'IA (Claude, OpenAI, DeepSeek ou Gemini). Aucun forfait ni carte bancaire : vous ne payez que les tokens utilisés auprès de votre fournisseur.

1. Installe le paquet

pip install translate-projects-django

2. Configurez settings.py

import os

INSTALLED_APPS = [
    # ...
    "translate_projects_django",
]

MIDDLEWARE = [
    # ...
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.locale.LocaleMiddleware",
    "django.middleware.common.CommonMiddleware",
    # ...
]

USE_I18N = True
LANGUAGE_CODE = "es"  # idioma base
LANGUAGES = [
    ("es", "Español"),
    ("en", "English"),
    ("pt-br", "Português (Brasil)"),
    ("fr", "Français"),
]
LOCALE_PATHS = [BASE_DIR / "locale"]
TRANSLATE_PROJECTS_API_KEY = os.environ.get("TRANSLATE_PROJECTS_API_KEY")

Les codes Django (pt-br, zh-hans) se convertissent automatiquement en ceux de l'API. LANGUAGE_CODE est votre langue de base et n'est jamais traduit.

3. Marquez vos textes comme d'habitude

Rien ne change dans ce que vous faites déjà avec Django : gettext en Python et {% translate %} dans les templates.

# views.py (ejemplo)
from django.utils.translation import gettext as _

def home(request):
    message = _("Cerrar sesión")
{# templates/home.html (ejemplo) #}
{% load i18n %}
<h1>{% translate "Bienvenido a tu panel" %}</h1>
<p>{% blocktranslate %}Hola {{ name }}, tienes mensajes nuevos{% endblocktranslate %}</p>

4. Traduis

export TRANSLATE_PROJECTS_API_KEY=tu_token
python manage.py translate

Sortie réelle (6 textes vers l'anglais, le portugais et le français) :

[05:19:47 PM] 🎯 Start Generate Translations
              📂 6 texts found in es
[05:19:48 PM] ✅ Sources unchanged, upload skipped
📝 Translating (en)    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
📝 Translating (pt-br) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
📝 Translating (fr)    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
[05:19:50 PM] ⏱ extract 0.0s · upload 0.4s · compile 0.0s · total 2.5s · 7 HTTP requests
                 en: 6 filled, 0 missing, 0 rejected · translate 1.4s · download 0.4s ·
              write 0.0s
                 pt-br: 6 filled, 0 missing, 0 rejected · translate 1.6s · download 0.1s ·
                 fr: 6 filled, 0 missing, 0 rejected · translate 1.8s · download 0.3s ·
              🎉 Translations completed ✅

Deux secondes et demie au total. La commande exécute makemessages, traduit jusqu'à 3 langues en parallèle, écrit les .po et se termine par compilemessages. Voici le français :

# locale/fr/LC_MESSAGES/django.po
#: demo/templates/demo.html:2
msgid "Bienvenido a tu panel"
msgstr "Bienvenue sur votre tableau de bord"

#: demo/templates/demo.html:3
#, python-format
msgid "Hola %(name)s, tienes mensajes nuevos"
msgstr "Bonjour %(name)s, vous avez de nouveaux messages"

#: demo/templates/demo.html:4
msgid "<b>Guardar</b> cambios"
msgstr "<b>Enregistrer</b> les modifications"

#: demo/templates/demo.html:5
#, python-format
msgid "100 %% gratis"
msgstr "100 %% gratuit"

#: demo/views.py:3
msgid "Cerrar sesión"
msgstr "Se déconnecter"

#: demo/views.py:3
msgid "Configuración de la cuenta"
msgstr "Paramètres du compte"

Fichiers générés

locale/
├── en/LC_MESSAGES/django.po    ← y su django.mo
├── pt_BR/LC_MESSAGES/django.po
├── fr/LC_MESSAGES/django.po
└── .translate-projects.json    ← caché

Validez (commit) les .po et .translate-projects.json pour que les autres machines et votre CI sautent les langues déjà à jour.

Commandes utiles

python manage.py translate --locale en   # solo un idioma
python manage.py translate --force       # descarga todo otra vez
  • Une seconde exécution sans nouveaux textes fait une seule requête et saute les langues complètes : ce qui est déjà traduit ne consomme pas de tokens.
  • Ne modifiez pas les .po à la main : ils sont reconstruits à chaque exécution. Modifiez la traduction dans le tableau de bord et lancez avec --force.
  • Limitation actuelle : les pluriels (ngettext, blocktranslate count) ne sont pas encore traduits et restent dans la langue de base.

Erreurs courantes

  • TRANSLATE_PROJECTS_API_KEY n'est pas défini dans settings.py : exportez la variable et lisez-la dans settings.py.
  • La langue source n'est pas la langue par défaut : LANGUAGE_CODE doit être la langue par défaut du projet.
  • MISSING_API_KEY : configurez le fournisseur, le modèle et la clé d'IA dans le projet.
  • CommandError : impossible de trouver msguniq ou xgettext : GNU gettext est manquant.

Le guide complet se trouve sur doc.translateprojects.dev. Créez votre projet gratuitement et traduisez votre projet Django dès aujourd'hui.