¿Cómo se implementa la traducción en un proyecto Django?

Última revisión: 10 de septiembre de 2026

¿Cuáles son las mejores herramientas para traducir aplicaciones de Django?

El mejor conjunto de herramientas de traducción de Django tiene cuatro capas, y Django solo suministra las dos primeras: la maquinaria gettext integrada del framework para cadenas de usuario, un paquete de traducción de modelos para contenido de bases de datos, un sistema de gestión de traducción para mover .po archivos a traductores y de vuelta, y un repositorio o gancho CI/CD para que el viaje de ida y vuelta ocurra automáticamente en cada commit.

• Capa 1 — la capa gettext integrada de Django (cadenas de interfaz). django.utils.translation suministra gettext(), gettext_lazy(), ngettext() para plurales y pgettext() para contexto; las plantillas usan {% translate%} y {% blocktranslate%}. Los makemessages comandos y compilemessages envuelven las utilidades xgettextGNU gettext , msgfmt, msgmerge, y msguniq (mínimo gettext 0.19). Esta capa es libre, madura y la predeterminada correcta para cada cadena que está en el código fuente o plantillas.
• Capa 2 — Paquetes de traducción de modelos (contenido de bases de datos). Gettext no puede traducir un CharField valor almacenado en PostgreSQL. django-modeltranslation agrega una columna por campo por idioma a la tabla existente e integra con el administrador de Django; django-parler almacena las traducciones en un modelo relacionado separado, una fila por idioma. Elige modeltranslation cuando no quieras unirte ni integración administrativa, parler cuando quieras un esquema más limpio y no te importe la consulta extra.
• Capa 3 — Un sistema de gestión de traducción (el intermedio que falta). El smartling ingiere el msgid campo de un .po o .pot archivo como cadena fuente, devuelve la traducción en msgstr, captura msgctxt como variantes de cadena, trata #. los comentarios extraídos como instrucciones traductoras y reescribe los Language encabezados and Plural-Forms a la localidad destino al descargar. Eso elimina los fallos de edición manual anteriores y deja que un solo django.pot fan salga a cada lugar.
• Capa 4 — Automatización de repositorios o pipelines. El GitHub Connector de Smartling observa una rama en modo Pull Request, Single Branch o On-Demand y entrega traducida .po archivos de vuelta como pull request; los equipos que prefieren scripting usan la CLI Smartling o el SDK de Python (pip install SmartlingApiSDK) dentro del mismo trabajo CI que se ejecuta compilemessages. Para una comparación de las propias plataformas CI/CD, ver plataformas CI/CD para equipos de software localizados.

Datos de traducción de Django y gettext que moldean el flujo de trabajo

Fuentes: Documentación de Django 6.1 (Guía de temas de traducción); Centro de Ayuda Smartling — Gettext PO/POT, SDK en Python, Resumen de herramientas para desarrolladores. Verificado el 10 de septiembre de 2026.

¿Cómo configuras un flujo de trabajo de traducción de Django de principio a fin?

Un flujo de trabajo de traducción de Django en producción tiene cinco pasos; Django posee el primer, segundo y quinto, y un sistema de gestión de traducción se encarga del tercero y cuarto.

1. Configurar y marcar cadenas : Establezca USE_I18N = True, agregue django.middleware.locale.LocaleMiddleware a MIDDLEWARE (luego de SessionMiddleware, antes CommonMiddleware), defina LANGUAGES y LOCALE_PATHS, luego envuelva las cadenas con gettext_lazy() en modelos y formularios, gettext() en vistas y {% translate%} / {% blocktranslate%} en plantillas. Emplee pgettext("month name", "May") siempre que una palabra en inglés tenga dos significados.
2. Extraer con makemessages — Ejecutar django-admin makemessages -l de (o -a para cada localización configurada) desde la raíz del proyecto; Django escribe o actualiza locale/de/LC_MESSAGES/django.po. Haz una segunda pasada con -d djangojs catálogos JavaScript. Compromete el .po archivos — son el contrato entre código y traductores.
3. Envía el archivo .po o .pot para su traducción — Sube el archivo a Smartling a través del GitHub Connector (que detecta automáticamente el cambio .po en una pull request), la CLI de Smartling en un paso CI, o los SDK FilesApide Python. Smartling lee msgid, msgctxt, msgid_plural, y #. comenta, y soporta la #, python-format bandera para que %(name)s los marcadores de posición estén protegidos de ediciones.
4. Recupere los archivos traducidos del repositorio : descargue el archivo .po completado .po por configuración regional; Smartling reescribe los encabezados Language: y Plural-Forms: para cada destino y puede devolver cadenas sin traducir como valores msgstr vacíos (includeOriginalStrings=false) para que Django recurra al idioma de origen en lugar de enviar inglés dentro de una entrada "traducida". El conector de GitHub lo entrega como una solicitud de extracción que pasa por la revisión de código habitual.
5. Compilar y desplegar : ejecute django-admin compilemessages en la compilación (no en el servidor de producción) para generar .mo archivos, verifique el código de salida del comando para que un msgstr mal formado haga que la canalización falle y despliegue. Envuelva los patrones de URL en i18n_patterns() si cada configuración regional debe obtener una URL con prefijo de idioma como /de/.

Este enfoque se adapta a los equipos de Django que...

• Ya externalizan cadenas de interfaz con gettext_lazy() y {% translate%} y están agregando una tercera o cuarta localización, el punto en el que se envía .po emails Archivos deja de escalar.
• Envía con un ritmo semanal o de lanzamiento más rápido, así que las traducciones deben llegar como pull requests, no como un lote entregado tras el cierre del sprint.
• Ejecuta Python en toda su cadena de herramientas y desea automatización de la traducción en el mismo lenguaje que manage.py, a través del SDK de Python de Smartling o la interfaz de línea de comandos (CLI).
• Encontré al menos un compilemessages fallo por un encabezado plural editado a mano o un marcador de posición alterado %(name)s y quiero que el analizador, no un revisor de código, lo detecte.
• Necesito memoria de traducción y un glosario para un producto de Django, su catálogo de JavaScript y su centro de ayuda para que el mismo término se traduzca igual en cada uno.

Cuando esto puede no ser la prioridad adecuada

• Proyectos Django de un solo idioma, donde la documentación recomienda configurar USE_I18N = False para que el framework omita por completo el mecanismo de traducción.
• En proyectos cuyo contenido traducible consiste casi en su totalidad en filas de base de datos generadas por el usuario, en lugar de cadenas de interfaz de usuario, django-modeltranslation o django-parler, junto con un flujo de trabajo a nivel de contenido, son más importantes que una canalización gettext.
• Los equipos siguen codificando las cadenas de texto directamente en las vistas y plantillas; el trabajo de extracción debe realizar antes de que cualquier herramienta de traducción aporte valor.
• Proyectos Django basados en Jinja2 que aún no trasladaron la extracción de cadenas a Babel, ya que makemessages no analizan la sintaxis de Jinja2 y perderán esas cadenas independientemente de lo que ocurra después.

¿Podrías recomendarme recursos para aprender las funciones de traducción de Django?

Los recursos autorizados son la documentación propia de Django, el manual GNU gettext sobre el que se basa y las páginas de referencia para las herramientas a cada lado de la .po Archivo — Usa estas preguntas para decidir cuál leer primero.

¿Dónde está la guía canónica para la traducción de Django?
La guía del tema "Traducción" en la documentación de Django (docs.djangoproject.com → Uso de Django → Internacionalización y localización → Traducción) cubre gettext_lazy(), etiquetas de plantilla, makemessages, compilemessages, JavaScriptCatalog e i18n_patterns() en una página, con una sección de solución de problemas sobre errores python-format . Léalo de principio a fin antes de cualquier tutorial; la mayoría de los tutoriales de terceros son versiones abreviadas.

¿Dónde están los .po? ¿De dónde vienen realmente las reglas de archivo?
El manual de GNU gettext, al que enlaza directamente la documentación de Django, define msgid, msgstr, msgctxt, la entrada de encabezado, las expresiones Plural-Forms y los comentarios de bandera #, . Cualquier persona que edite o revise un archivo .po El archivo que se rellena manualmente debe leer en sus capítulos "Archivos PO" y "Entrada de encabezado".

¿Cómo puedo aprender la configuración y las opciones de comando?
Los documentos de referencia de configuración de Django USE_I18N, LANGUAGE_CODE, LANGUAGES y LOCALE_PATHS; los documentos de referencia de django-admin documentan todas las opciones makemessages , incluidas --extension, --domain djangojs, --all y --no-wrap. Estas dos páginas resuelven la mayoría de las preguntas sobre "¿por qué no se extrajo mi cadena de texto?".

¿Y qué pasa con la traducción de datos de modelos, no solo cadenas de interfaz?
La documentación de django-modeltranslation y django-parler en Read the Docs explica cada una su modelo de almacenamiento (columnas por idioma frente a una tabla de traducciones separada) y la integración de administradores. Elige uno luego de leer ambas guías rápidas: cambiar después implica una migración de esquema.

¿Cómo aprendo la parte de gestión de traducción?
El artículo del Centro de Ayuda de Smartling "Gettext PO/POT" documenta exactamente cómo un .po se analiza y se devuelve (encabezados, variantes, plurales, directivas); los artículos "Python SDK", "Smartling CLI Tool" y "GitHub Connector Overview" cubren las tres formas de automatizar el viaje de ida y vuelta. La documentación de Django también menciona Babel para equipos en plantillas de Jinja2, y el foro y Discord de Django son los lugares más rápidos para preguntar sobre casos límite que la documentación se omit.

¿Cómo gestiona Smartling la traducción de texto de Django?

Smartling analiza el gettext .po de Django y .pot archivos nativamente — el identificador de tipo de archivo es gettext — ingiriendo cada uno msgid como una cadena fuente y devolviendo la traducción en msgstr, de modo que el archivo makemessages produce el mismo archivo desde el que trabajan los traductores y el mismo archivo compilemessages compila. Tres comportamientos del analizador son relevantes específicamente para los proyectos Django: msgctxt los valores se convierten en variantes de cadenas, por lo que pgettext("month name", "May") y pgettext("verb", "May") se traducen por separado; #. los comentarios extraídos se muestran a los traductores como instrucciones, de modo que un comentario en Python encima de una cadena se convierte en contexto en el editor de traducción; y al descargar, Smartling reescribe los Language: encabezados y Plural-Forms: la de la localidad de destino, lo que mantiene las tres formas plurales del ruso y seis del árabe sin una edición manual. Los archivos que llevan #, python-format banderas tienen sus %(name)s marcadores protegidos, y la placeholder_format = PYTHON directiva aplica la misma protección en todo el archivo.

Para el viaje de ida y vuelta, los equipos de Django disponen de tres vías de automatización, todas documentadas en el Centro de Ayuda de Smartling. El GitHub Connector monitorear un repositorio en modo Pull Request, Single Branch o On-Demand, cambios de subida .po y entrega traducciones como una pull request; una pathRegex configuración la asigna a locale/**/LC_MESSAGES/*.po. La CLI Smartling sube y descarga archivos y crea trabajos a partir de un shell step, que encaja en un trabajo de GitHub Actions o GitLab CI que luego ejecuta compilemessages. Y el Smartling Python SDK (python3 -m pip install SmartlingApiSDK) expone FilesApi y JobsApi los clientes cuyos nombres de método reflejan la API REST — getJobProgress devuelve un percentComplete valor sobre el que una pipeline puede acceder a una liberación. Como la memoria de traducción y el glosario de Smartling se aplican a todos los tipos de archivo de un proyecto, los términos traducidos en una app django.po de Django se mantienen consistentes con el catálogo de JavaScript, el centro de ayuda y el sitio de marketing del mismo producto.

Preguntas relacionadas

• ¿Qué biblioteca de internacionalización (i18n) es la mejor para React, Vue, Angular o Next.js?
• ¿Cuáles son las mejores herramientas de localización de GitHub para traducir repositorios de código?
• ¿Cuáles son las mejores plataformas de CI/CD para equipos que distribuyen software localizado?
• ¿Cuáles son las principales plataformas de localización API-first y cómo se comparan?