Once the string literals of an application have been tagged for later translation, the translation themselves need to be written (or obtained). Here\u2019s how that works.<\/p>\n
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.<\/p>\n
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:<\/p>\n
django-admin makemessages -l de<\/p>\n
\u2026 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.<\/p>\n
The script should be run from one of two places:<\/p>\n
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.<\/p>\n
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.<\/p>\n
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:<\/p>\n
django-admin makemessages -l de -e txt<\/p>\n
Separate multiple extensions with commas and\/or use -e or –extension multiple times:<\/p>\n
django-admin makemessages -l de -e html,txt -e xml<\/p>\n
When creating message files from JavaScript source code you need to use the special \u2018djangojs\u2019 domain, not -e js.<\/p>\n
If you don\u2019t have the gettext utilities installed, makemessages will create empty files. If that\u2019s 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\u2019s just an empty translation file.<\/p>\n
If you\u2019re 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\u2019s contact information, but the bulk of the file is a list of messages \u2013 simple mappings between translation strings and the actual translated text for the particular language.<\/p>\n
For example, if your Django app contained a translation string for the text “Welcome to my site.”, like so:<\/p>\n
_(“Welcome to my site.”)<\/p>\n
\u2026 then django-admin makemessages will have created a .po file containing the following snippet \u2013 a message:<\/p>\n
#: path\/to\/python\/module.py:23
\nmsgid “Welcome to my site.”
\nmsgstr “”<\/p>\n
A quick explanation:<\/p>\n
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\u2019t forget trailing spaces within the strings; otherwise, they\u2019ll be tacked together without white-space!<\/p>\n
Due to the way the gettext tools work internally and because we want to allow non-ASCII source strings in Django\u2019s 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.<\/p>\n
To re-examine all source code and templates for new translation strings and update all message files for all languages, run this:<\/p>\n
django-admin makemessages -a<\/p>\n
After you create your message file \u2013 and each time you make changes to it \u2013 you\u2019ll need to compile it into a more efficient form, for use by gettext. Do this with the django-admin compilemessages utility.<\/p>\n
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:<\/p>\n
django-admin compilemessages<\/p>\n
That\u2019s it. Your translations are ready for use.<\/p>\n
If you\u2019re using Windows and need to install the GNU gettext utilities so django-admin compilemessages works.<\/p>\n
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.<\/p>\n
You create and update the message files the same way as the other Django message files \u2013 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:<\/p>\n
django-admin makemessages -d djangojs -l de<\/p>\n
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.<\/p>\n
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:<\/p>\n
Download the following zip files from the GNOME servers:<\/p>\n
(X is the version number; version 0.15 or higher is required.)<\/p>\n
Extract the contents of the bin\\ directories in both files to the same folder on your system (i.e. C:\\Program Files\\gettext-utils)<\/p>\n
Update the system PATH:<\/p>\n
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
\nentered at a Windows command prompt causes a popup window saying xgettext.exe has generated errors and will be closed by Windows.<\/p>\n
If you want to pass additional parameters to xgettext, you need to create a custom makemessages command and override its xgettext_options attribute:<\/p>\n
from django.core.management.commands import makemessages<\/p>\n
class Command(makemessages.Command):
\nxgettext_options = makemessages.Command.xgettext_options + [‘–keyword=mytrans’]\n
If you need more flexibility, you could also add a new argument to your custom makemessages command:<\/p>\n
from django.core.management.commands import makemessages<\/p>\n
class Command(makemessages.Command):<\/p>\n
def add_arguments(self, parser):
\nsuper(Command, self).add_arguments(parser)
\nparser.add_argument(‘–extra-keyword’,
\ndest=’xgettext_keywords’,
\naction=’append’)<\/p>\n
def handle(self, *args, **options):
\nxgettext_keywords = options.pop(‘xgettext_keywords’)
\nif xgettext_keywords:
\nself.xgettext_options = (
\nmakemessages.Command.xgettext_options[:] +
\n[‘–keyword=%s’ % kwd for kwd in xgettext_keywords]\n)
\nsuper(Command, self).handle(*args, **options)<\/p>\n
You may want to set the active language for the current session explicitly. Perhaps a user\u2019s language preference is retrieved from another system, for example. You\u2019ve 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:<\/p>\n
from django.utils import translation
\nuser_language = ‘fr’
\ntranslation.activate(user_language)
\nrequest.session[translation.LANGUAGE_SESSION_KEY] = user_language<\/p>\n
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.<\/p>\n
If you are not using sessions, the language will persist in a cookie, whose name is configured in LANGUAGE_COOKIE_NAME. For example:<\/p>\n
from django.utils import translation
\nfrom django import http
\nfrom django.conf import settings
\nuser_language = ‘fr’
\ntranslation.activate(user_language)
\nresponse = http.HttpResponse(…)
\nresponse.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)<\/p>\n\n\n