Saltar al contenido principal

Django

El paquete translate-projects-django añade el comando python manage.py translate: extrae tus textos, los traduce a cada idioma de settings.LANGUAGES, escribe los archivos .po y los compila.

Requisitos​

  • Python 3.8 o superior y Django 3.2 o superior.
  • GNU gettext (xgettext y msgfmt), igual que cualquier traducción en Django. En Windows usa gettext para Windows.
  • Un proyecto y un API token de Translate Projects. Mira Primeros pasos.
Instalar gettext
# Debian / Ubuntu
sudo apt-get install gettext
# macOS
brew install gettext
# Docker
RUN apt-get update && apt-get install -y gettext

1. Instala el paquete​

Terminal
pip install translate-projects-django

2. Configura 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"  # Idioma base: el idioma por defecto del proyecto

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

LOCALE_PATHS = [BASE_DIR / "locale"]  # Se usa la primera ruta

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

# Opcional: carpetas que makemessages ignora
TRANSLATE_PROJECTS_EXCLUDE_DIRS = ["venv/*", "node_modules/*"]
AjusteObligatorioDescripción
TRANSLATE_PROJECTS_API_KEYSíAPI token del proyecto. Léelo de una variable de entorno.
LANGUAGE_CODESíIdioma base. Nunca se traduce.
LANGUAGESSíIdiomas destino, con los códigos de Django (pt-br, zh-hans); se convierten solos a los de la API (pt-BR, zh-Hans).
LOCALE_PATHSSíDónde se escriben los archivos .po (la primera ruta).
TRANSLATE_PROJECTS_EXCLUDE_DIRSNoSe pasa a makemessages --ignore.

3. Marca tus textos​

Usa las herramientas estándar 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. Traduce​

Terminal
export TRANSLATE_PROJECTS_API_KEY=tu_token
python manage.py translate               # Todos los idiomas de LANGUAGES
python manage.py translate --locale en   # Solo un idioma
python manage.py translate --force       # Descarga todo otra vez

El idioma de --locale debe estar en LANGUAGES y ser distinto de LANGUAGE_CODE. Con --locale fr --force solo se vuelve a traducir ese idioma.

Traducción en la terminal

Archivos que genera​

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

El comando ejecuta makemessages para el idioma base, traduce hasta 3 idiomas en paralelo, escribe los .po (pt-br se convierte en pt_BR) y termina con compilemessages. Las traducciones que cambian un placeholder (%(name)s, %s, {name}) se descartan para que compilemessages nunca falle.

  • Cada .po traducido se reconstruye desde el .po del idioma base cada vez que se traduce ese idioma, así que las ediciones a mano se pierden. Edita las traducciones en el panel y ejecuta con --force.
  • Haz commit de los .po y de .translate-projects.json para que otras máquinas y tu CI salten los idiomas que ya están al día. Los .mo puedes subirlos o generarlos en el despliegue con compilemessages.
  • Los textos en plural (ngettext, blocktranslate count) todavía no se traducen: quedan en el idioma base.

Resultado

Caché y --force​

Una segunda ejecución sin textos nuevos hace una sola petición y salta los idiomas que ya están completos (se guarda en locale/.translate-projects.json). Usa --force para descargar todo de nuevo, por ejemplo después de editar traducciones en el panel. Más detalles en Caché y errores.

Errores comunes​

  • TRANSLATE_PROJECTS_API_KEY is not set in settings.py: exporta la variable y léela en settings.py.
  • Token inválido (Token no válido): copia de nuevo el token del proyecto. Los .po existentes no se tocan.
  • El idioma de origen no es el predeterminado: LANGUAGE_CODE debe ser el idioma por defecto del proyecto.
  • Falta la key de IA (MISSING_API_KEY): configura el proveedor, el modelo y la key en el proyecto; los textos que faltan se reintentan en la siguiente ejecución.
  • Traducción parcial, errores 5xx o de red: se reintenta automáticamente y los idiomas incompletos se vuelven a pedir en la siguiente ejecución.
  • CommandError: Can't find msguniq o xgettext: falta GNU gettext; instálalo como se indica en Requisitos.
Gratis

🚀 Automatiza tus traducciones gratis​

Translate Projects es gratuito. Creas tu proyecto, conectas la key de tu proveedor de IA y solo le pagas a él lo que gastes.

  • Sin planes ni tarjeta de crédito: Todas las funciones están disponibles desde el primer día.
  • Usa tu propia IA: Claude, OpenAI, DeepSeek o Gemini. Tu key se guarda cifrada.
  • Red de traducciones compartida: Si un texto ya fue traducido, lo recibes al instante sin gastar tu key.
  • Panel de administración: Revisa y edita todas tus traducciones desde un solo lugar.

Crear cuenta gratis →

Soporte

Estamos aquí para ayudarte​

Si tienes alguna pregunta, necesitas ayuda o quieres contribuir, no dudes en contactarme. Estoy a tu disposición para apoyarte en lo que necesites.

Apoya el Proyecto​

Si este proyecto te ha sido útil, te invito a invitarme un café. Tu apoyo me ayuda a seguir mejorando y creando contenido de valor. ¡Gracias por estar aquí! ☕

Buy me a coffee