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.
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.
makemessages command (and
compilemessages discussed later) use commands from the GNU
The minimum version of the
gettext utilities supported is 0.15.
To create or update a message file, run this command:
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
- 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 (see how-django-discovers-translations and be sure
LOCALE_PATHS is configured correctly). It creates (or updates) a message file in the directory
locale/LANG/LC_MESSAGES. In the
de example, the file will be
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.
django-admin makemessages examines every file that has the
.txt file extension. In case you want to override that default, use the
-e option to specify the file extensions to examine:
Separate multiple extensions with commas and/or use
--extension multiple times:
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, see “
gettext on windows” a little later in the chapter for more information.
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:
django-admin makemessages will have created a
.po file containing the following snippet – a message:
A quick explanation:
msgidis the translation string, which appears in the source. Don’t change it.
msgstris 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
msgidline, 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
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:
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:
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, see
gettext on Windows below for more information.
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.
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
parlance is known as a domain in this case the
djangojs domain, by providing a
-d djangojs parameter, like this:
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
- Download the following zip files from the GNOME servers:
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.
- Update the system PATH:
Control Panel > System > Advanced > Environment Variables.
- In the
System variableslist, click
;C:\Program Files\gettext-utils\binat the end of the
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
entered at a Windows command prompt causes a popup window saying xgettext.exe has generated errors and will be closed by Windows.
Customizing The Makemessages Command
If you want to pass additional parameters to
xgettext, you need to create a custom
makemessages command and override its
If you need more flexibility, you could also add a new argument to your custom
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:
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: