Ver índice de contenidos del libro

18.3. Creando archivos de idioma

Una vez que hayas etiquetado tus cadenas para su posterior traducción, necesitas escribir (u obtener) las traducciones propiamente dichas. En esta sección explicaremos como es que eso funciona.

18.3.1. Creando los archivos de mensajes

El primer paso es crear un archivo de mensajes para un nuevo idioma. Un archivo de mensajes es un archivo de texto común que representa un único idioma que contiene todas las cadenas de traducción disponibles y cómo deben ser representadas las mismas en el idioma en cuestión. Los archivos de mensajes tiene una extensión .po.

Django incluye una herramienta, bin/make-messages, que automatiza la creación y el mantenimiento de dichos archivos.

Para crear o actualizar un archivo de mensajes, ejecuta este comando:

$ bin/make-messages.py -l de

donde de es el código de idioma para el archivo de mensajes que deseas crear. El código de idioma en este caso está en formato locale. Por ejemplo, el mismo es pt_BR para portugués de Brasil y de_AT para alemán de Austria. Echa un vistazo a los códigos de idioma en el directorio django/conf/locale/ para ver cuales son los idiomas actualmente incluidos.

El script debe ser ejecutado desde una de tres ubicaciones:

  • El directorio raíz django (no una copia de trabajo de Subversion, sino el que se halla referenciado por $PYTHONPATH o que se encuentra en algún punto debajo de esa ruta.
  • El directorio raíz de tu proyecto Django
  • El directorio raíz de tu aplicación Django

El script recorre completamente el árbol en el cual es ejecutado y extrae todas las cadenas marcadas para traducción. Crea (o actualiza) un archivo de mensajes en el directorio conf/locale. En el ejemplo de, el archivo será conf/locale/de/LC_MESSAGES/django.po.

Si es ejecutado sobre el árbol de tu proyecto o tu aplicación, hará lo mismo pero la ubicación del directorio locale es locale/LANG/LC_MESSAGES (nota que no tiene un prefijo conf). La primera vez que lo ejecutes en tu árbol necesitarás crear el directorio locale.

Nota Si no tienes instaladas las utilidades gettext, make-messages.py creará archivos vacíos. Si te encuentras ante esa situación debes o instalar dichas utilidades o simplemente copiar el archivo de mensajes de inglés (conf/locale/en/LC_MESSAGES/django.po) y usar el mismo como un punto de partida; se trata simplemente de un archivo de traducción vacío.

El formato de los archivos .po es sencillo. Cada archivo .po contiene una pequeña cantidad de metadatos tales como la información de contacto de quiénes mantienen la traducción, pero el grueso del archivo es una lista de mensajes — mapeos simples entre las cadenas de traducción y las traducciones al idioma en cuestión propiamente dichas.

Por ejemplo, si tu aplicación Django contiene una cadena de traducción para el texto Welcome to my site:

_("Welcome to my site.")

entonces make-messages.py habrá creado un archivo .po que contendrá el siguiente fragmento — un mensaje:

#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""

Es necesaria una rápida explicación:

  • msgid es la cadena de traducción, la cual aparece en el código fuente. No la modifiques.
  • msgstr es donde colocas la traducción específica a un idioma. Su valor inicial es vacío de manera que es tu responsabilidad el cambiar esto. Asegúrate de que mantienes las comillas alrededor de tu traducción.
  • Por conveniencia, cada mensaje incluye el nombre del archivo y el número de línea desde el cual la cadena de traducción fue extraída.

Los mensajes largos son un caso especial. La primera cadena inmediatamente a continuación de msgstr (o msgid) es una cadena vacía. El contenido en si mismo se encontrará en las próximas líneas con el formato de una cadena por línea. Dichas cadenas se concatenan en forma directa. ¡No olvides los espacios al final de las cadenas; en caso contrario todas serán agrupadas sin espacios entre las mismas!.

Por ejemplo, a continuación vemos una traducción de múltiples líneas (extraída de la localización al español incluida con Django):

msgid ""
"There's been an error. It's been reported to the site administrators via e-"
"mail and should be fixed shortly. Thanks for your patience."
msgstr ""
"Ha ocurrido un error. Se ha informado a los administradores del sitio "
"mediante correo electrónico y debería arreglarse en breve. Gracias por su "
"paciencia."

Notar los espacios finales.

Nota Cuando crees un archivo .po con tu editor de texto favorito, primero edita la línea del conjunto de caracteres (busca por el texto "CHARSET") y fija su valor al del conjunto de caracteres usarás para editar el contenido. Generalmente, UTF-8 debería funcionar para la mayoría de los idiomas pero gettext debería poder manejar cualquier conjunto de caracteres.

Para reexaminar todo el código fuente y las plantillas en búsqueda de nuevas cadenas de traducción y actualizar todos los archivos de mensajes para todos los idiomas, ejecuta lo siguiente:

$ make-messages.py -a

18.3.2. Compilando archivos de mensajes

Luego de que has creado tu archivo de mensajes, y cada vez que realices cambios sobre el mismo necesitarás compilarlo a una forma más eficiente, según los usa gettext. Usa para ello la utilidad bin/compile-messages.py.

Esta herramienta recorre todos los archivos .po disponibles y crea archivos .mo, los cuales son archivos binarios optimizados para su uso por parte de gettext. En el mismo directorio desde el cual ejecutaste make-messages.py, ejecuta compile-messages.py de la siguiente manera:

$ bin/compile-messages.py

Y eso es todo. Tus traducciones están listas para ser usadas.