Creating Language Files

Once the string literals of an application have been tagged for later translation, the translation themselves need to be written (or obtained). Here’s how that works.

Message Files

The first step is to create a message file for a new language. A message file is a plain-text file, representing a single language, that contains all available translation strings and how they should be represented in the given language. Message files have a .po file extension.

Django comes with a tool, django-admin makemessages, that automates the creation and upkeep of these files. The makemessages command (and compilemessages discussed later) use commands from the GNU gettext toolset: xgettext, msgfmt, msgmerge and msguniq. The minimum version of the gettext utilities supported is 0.15. To create or update a message file, run this command:

django-admin makemessages -l de

… where de is the locale name for the message file you want to create. For example, pt_BR for Brazilian Portuguese, de_AT for Austrian German or id for Indonesian.

The script should be run from one of two places:

•  The root directory of your Django project (the one that contains manage.py).
• The root directory of one of your Django apps.

The script runs over your project source tree or your application source tree and pulls out all strings marked for translation. It creates (or updates) a message file in the directory locale/LANG/LC_MESSAGES. In the de example, the file will be locale/de/LC_MESSAGES/django.po.

When you run makemessages from the root directory of your project, the extracted strings will be automatically distributed to the proper message files. That is, a string extracted from a file of an app containing a locale directory will go in a message file under that directory. A string extracted from a file of an app without any locale directory will either go in a message file under the directory listed first in LOCALE_PATHS or will generate an error if LOCALE_PATHS is empty.

By default, django-admin makemessages examines every file that has the .html or .txt file extension. In case you want to override that default, use the –extension or -e option to specify the file extensions to examine:

django-admin makemessages -l de -e txt

Separate multiple extensions with commas and/or use -e or –extension multiple times:

django-admin makemessages -l de -e html,txt -e xml

When creating message files from JavaScript source code you need to use the special ‘djangojs’ domain, not -e js.

If you don’t have the gettext utilities installed, makemessages will create empty files. If that’s the case, either install the gettext utilities or just copy the English message file (locale/en/LC_MESSAGES/django.po) if available and use it as a starting point; it’s just an empty translation file.

If you’re using Windows and need to install the GNU gettext utilities so makemessages works. The format of .po files is straightforward. Each .po file contains a small bit of metadata, such as the translation maintainer’s contact information, but the bulk of the file is a list of messages – simple mappings between translation strings and the actual translated text for the particular language.

For example, if your Django app contained a translation string for the text “Welcome to my site.”, like so:

_(“Welcome to my site.”)

… then django-admin makemessages will have created a .po file containing the following snippet – a message:

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

A quick explanation:

•  msgid is the translation string, which appears in the source. Don’t change it.
• msgstr is where you put the language-specific translation. It starts out empty, so it’s your responsibility to change it. Make sure you keep the quotes around your translation.
• As a convenience, each message includes, in the form of a comment line prefixed with # and located above the msgid line, the filename and line number from which the translation string was gleaned.

Long messages are a special case. There, the first string directly after the msgstr (or msgid) is an empty string. Then the content itself will be written over the next few lines as one string per line. Those strings are directly concatenated. Don’t forget trailing spaces within the strings; otherwise, they’ll be tacked together without white-space!

Due to the way the gettext tools work internally and because we want to allow non-ASCII source strings in Django’s core and your applications, you must use UTF-8 as the encoding for your PO files (the default when PO files are created). This means that everybody will be using the same encoding, which is important when Django processes the PO files.

To re-examine all source code and templates for new translation strings and update all message files for all languages, run this:

django-admin makemessages -a

Compiling Message Files

After you create your message file – and each time you make changes to it – you’ll need to compile it into a more efficient form, for use by gettext. Do this with the django-admin compilemessages utility.

This tool runs over all available .po files and creates .mo files, which are binary files optimized for use by gettext. In the same directory from which you ran django-admin makemessages, run:

django-admin compilemessages

That’s it. Your translations are ready for use.

If you’re using Windows and need to install the GNU gettext utilities so django-admin compilemessages works.

Django only supports .po files encoded in UTF-8 and without any BOM (Byte Order Mark) so if your text editor adds such marks to the beginning of files by default then you will need to reconfigure it.

Creating Message Files from Javascript Source Code

You create and update the message files the same way as the other Django message files – with the django-admin makemessages tool. The only difference is you need to explicitly specify what in gettext parlance is known as a domain in this case the djangojs domain, by providing a -d djangojs parameter, like this:

django-admin makemessages -d djangojs -l de

This would create or update the message file for JavaScript for German. After updating message files, just run django-admin compilemessages the same way as you do with normal Django message files.

gettext On Windows

This is only needed for people who either want to extract message IDs or compile message files (.po). Translation work itself just involves editing existing files of this type, but if you want to create your own message files, or want to test or compile a changed message file, you will need the gettext utilities:

Download the following zip files from the GNOME servers:

• gettext-runtime-X.zip
• gettext-tools-X.zip

(X is the version number; version 0.15 or higher is required.)

Extract the contents of the bin\ directories in both files to the same folder on your system (i.e. C:\Program Files\gettext-utils)

Update the system PATH:

• Control Panel > System > Advanced > Environment Variables.
• In the System variables list, click Path, click Edit.
• Add ;C:\Program Files\gettext-utils\bin at the end of the Variable value field.

You may also use gettext binaries you have obtained elsewhere, so long as the xgettext –version command works properly. Do not attempt to use Django translation utilities with a gettext package if the command xgettext –version
entered at a Windows command prompt causes a popup window saying xgettext.exe has generated errors and will be closed by Windows.

Customizing The Make messages Command

If you want to pass additional parameters to xgettext, you need to create a custom makemessages command and override its xgettext_options attribute:

from django.core.management.commands import makemessages

class Command(makemessages.Command):
xgettext_options = makemessages.Command.xgettext_options + [‘–keyword=mytrans’]

If you need more flexibility, you could also add a new argument to your custom makemessages command:

from django.core.management.commands import makemessages

class Command(makemessages.Command):

def add_arguments(self, parser):
super(Command, self).add_arguments(parser)
parser.add_argument(‘–extra-keyword’,
dest=’xgettext_keywords’,
action=’append’)

def handle(self, *args, **options):
xgettext_keywords = options.pop(‘xgettext_keywords’)
if xgettext_keywords:
self.xgettext_options = (
makemessages.Command.xgettext_options[:] +
[‘–keyword=%s’ % kwd for kwd in xgettext_keywords] )
super(Command, self).handle(*args, **options)

Explicitly Setting the Active Language

You may want to set the active language for the current session explicitly. Perhaps a user’s language preference is retrieved from another system, for example. You’ve already been introduced to django.utils.translation.activate(). That applies to the current thread only. To persist the language for the entire session, also modify LANGUAGE_SESSION_KEY in the session:

from django.utils import translation
user_language = ‘fr’
translation.activate(user_language)
request.session[translation.LANGUAGE_SESSION_KEY] = user_language

You would typically want to use both: django.utils.translation.activate() will change the language for this thread, and modifying the session makes this preference persist in future requests.

If you are not using sessions, the language will persist in a cookie, whose name is configured in LANGUAGE_COOKIE_NAME. For example:

from django.utils import translation
from django import http
from django.conf import settings
user_language = ‘fr’
translation.activate(user_language)
response = http.HttpResponse(…)
response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)

Back to Tutorial