Django

Le paquet translate-projects-django ajoute la commande python manage.py translate : il extrait vos textes, les traduit dans chaque langue de settings.LANGUAGES, écrit les fichiers .po et les compile.

Prérequis

• Python 3.8 ou supérieur et Django 3.2 ou supérieur.
• GNU gettext (xgettext et msgfmt), comme pour toute traduction dans Django. Sous Windows, utilisez gettext para Windows.
• Un projet et un token API de Translate Projects. Consulte Premiers pas.

Installer gettext

# Debian / Ubuntu
sudo apt-get install gettext
# macOS
brew install gettext
# Docker
RUN apt-get update && apt-get install -y gettext

1. Installe le paquet

Terminal

pip install translate-projects-django

2. Configurez settings.py

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"  # Langue de base : la langue par défaut du projet

LANGUAGES = [
    ("es", "Español"),
    ("en", "English"),
    ("pt-br", "Português (Brasil)"),
    ("fr", "Français"),
]

LOCALE_PATHS = [BASE_DIR / "locale"]  # Le premier chemin est utilisé

TRANSLATE_PROJECTS_API_KEY = os.environ.get("TRANSLATE_PROJECTS_API_KEY")

# Facultatif : dossiers ignorés par makemessages
TRANSLATE_PROJECTS_EXCLUDE_DIRS = ["venv/*", "node_modules/*"]

Ajuste	Obligatorio	Description
TRANSLATE_PROJECTS_API_KEY	Sí	Jeton API du projet. Lisez-le depuis une variable d'environnement.
LANGUAGE_CODE	Sí	Langue de base. Elle n'est jamais traduite.
LANGUAGES	Sí	Langues cibles, avec les codes Django (pt-br, zh-hans) ; ils sont convertis automatiquement en codes de l'API (pt-BR, zh-Hans).
LOCALE_PATHS	Sí	Emplacement où les fichiers .po sont écrits (le premier chemin).
TRANSLATE_PROJECTS_EXCLUDE_DIRS	Non	Transmis à makemessages --ignore.

3. Marca tus textos

Utilisez les outils standard de Django :

views.py

from django.utils.translation import gettext as _

def home(request):
    message = _("Bienvenido a mi sitio")

templates/home.html

{% load i18n %}
<html lang="{{ LANGUAGE_CODE }}">
  <h1>{% translate "Hola mundo" %}</h1>
</html>

4. Traduis

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
python manage.py translate               # Toutes les langues de LANGUAGES
python manage.py translate --locale en   # Une seule langue
python manage.py translate --force       # Tout télécharger à nouveau

La langue de --locale doit figurer dans LANGUAGES et être différente de LANGUAGE_CODE. Avec --locale fr --force, seule cette langue est retraduite.

Fichiers générés

locale/
├── en/LC_MESSAGES/django.po    ← et son django.mo compilé
├── pt_BR/LC_MESSAGES/django.po
├── fr/LC_MESSAGES/django.po
└── .translate-projects.json    ← cache

La commande exécute makemessages pour la langue de base, traduit jusqu'à 3 langues en parallèle, écrit les .po (pt-br devient pt_BR) et se termine par compilemessages. Les traductions qui modifient un placeholder (%(name)s, %s, {name}) sont rejetées afin que compilemessages n'échoue jamais.

• Chaque .po traduit est reconstruit à partir du .po de la langue de base à chaque traduction de cette langue, donc les modifications manuelles sont perdues. Modifiez les traductions dans le tableau de bord et exécutez avec --force.
• Faites un commit des .po et de .translate-projects.json pour que les autres machines et votre CI sautent les langues déjà à jour. Vous pouvez envoyer les .mo ou les générer au déploiement avec compilemessages.
• Les textes au pluriel (ngettext, blocktranslate count) ne sont pas encore traduits : ils restent dans la langue de base.

Cache et --force

Une deuxième exécution sans nouveaux textes ne fait qu'une seule requête et saute les langues déjà complètes (cela est enregistré dans locale/.translate-projects.json). Utilisez --force pour tout télécharger à nouveau, par exemple après avoir modifié des traductions dans le panneau. Plus de détails dans Cache et erreurs.

Erreurs courantes

• TRANSLATE_PROJECTS_API_KEY is not set in settings.py: exportez la variable et lisez-la dans settings.py.
• Token invalide (Token no válido): copiez de nouveau le token du projet. Les .po existants ne sont pas modifiés.
• La langue source n'est pas la langue par défaut: LANGUAGE_CODE doit être la langue par défaut du projet.
• Clé d'IA manquante (MISSING_API_KEY): configurez le fournisseur, le modèle et la clé dans le projet ; les textes manquants seront réessayés lors de la prochaine exécution.
• Traduction partielle, erreurs 5xx ou réseau: est réessayé automatiquement et les langues incomplètes sont redemandées lors de la prochaine exécution.
• CommandError: Can't find msguniq ou xgettext: GNU gettext est absent ; installez-le comme indiqué dans Prérequis.

Gratuit

🚀 Automatisez vos traductions gratuitement

Translate Projects est gratuit. Vous créez votre projet, connectez la clé de votre fournisseur d'IA et ne lui payez que ce que vous dépensez.

• Sans forfaits ni carte de crédit: Toutes les fonctionnalités sont disponibles dès le premier jour.
• Utilisez votre propre IA: Claude, OpenAI, DeepSeek ou Gemini. Votre clé est stockée chiffrée.
• Réseau de traductions partagé: Si un texte a déjà été traduit, vous le recevez instantanément sans dépenser votre clé.
• Panneau d'administration: Vérifiez et modifiez toutes vos traductions depuis un seul endroit.

Créer un compte gratuitement →

Support

Nous sommes là pour vous aider

Si vous avez des questions, besoin d'aide ou souhaitez contribuer, n'hésitez pas à me contacter. Je suis à votre disposition pour vous soutenir dans tout ce dont vous avez besoin.

• Site web: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Soutenez le projet

Si ce projet vous a été utile, je vous invite à m'offrir un café. Votre soutien m'aide à continuer de m'améliorer et à créer du contenu de valeur. Merci d'être là ! ☕