The Django Book

Specifying Translation Strings in Python Code

Translation strings specify “This text should be translated.” These strings can appear in your Python code and templates. It’s your responsibility to mark translatable strings; the system can only translate strings it knows about.

def my_view(request):
    output = _("Welcome to my site.")
    return HttpResponse(output)

from django.utils.translation import gettext
def my_view(request):
    output = gettext("Welcome to my site.")
    return HttpResponse(output)

def my_view(request):
    words = ['Welcome', 'to', 'my', 'site.']
    output = _(' '.join(words))
    return HttpResponse(output)

def my_view(request):
    sentence = 'Welcome to my site.'
    output = _(sentence)
    return HttpResponse(output)

def my_view(request, n):
    output = _('%(name)s is my name.') % {'name': n}
    return HttpResponse(output)

from django.utils.translation import gettext_lazy

class MyThing(models.Model):
    name = models.CharField(help_text=gettext_lazy('This is the help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_('This is the help text'))
    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('mythings')

from django.utils.translation import ngettext
def hello_world(request, count):
    page = ngettext(
        'there is %(count)d object',
        'there are %(count)d objects', count
    ) % {'count': count}
    return HttpResponse(page)

Specifying Translation Strings in Template Code

Using translations in Django templates uses two template tags and a slightly different syntax than in Python code. To give your template access to these tags, put {% load i18n %} toward the top of your template.

The {% trans %} template tag marks a string for translations:

<title>{% trans "This is the title." %}</title>

If you only want to mark a value for translation, but translate it later, use the noop option:

<title>{% trans "value" noop %}</title>

It’s not possible to use template variables in {% trans %} — only constant strings, in single or double quotes, are allowed. If your translations require variables (placeholders), use {% blocktrans %}, for example:

{% blocktrans %}This will have {{ value }} inside.{% endblocktrans %}

To translate a template expression — say, using template filters — you need to bind the expression to a local variable for use within the translation block:

{% blocktrans with value|filter as myvar %}
  This will have {{ myvar }} inside.
{% endblocktrans %}

If you need to bind more than one expression inside a blocktrans tag, separate the pieces with and:

{% blocktrans with book|title as book_t and author|title as author_t %}
  This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}

To pluralize, specify both the singular and plural forms with the {% plural %} tag, which appears within {% blocktrans %} and {% endblocktrans %}, for example:

{% blocktrans count list|length as counter %}
  There is only one {{ name }} object.
{% plural %}
  There are {{ counter }} {{ name }} objects.
{% endblocktrans %}

Internally, all block and inline translations use the appropriate gettext/ngettext call.

When you use RequestContext (see Chapter 10), your templates have access to three translation-specific variables:

• {{ LANGUAGES }} is a list of tuples in which the first element is the language code and the second is the language name (in that language).
• {{ LANGUAGE_CODE }} is the current user’s preferred language, as a string (e.g., en-us). (See the “How Django Discovers Language Preference” section for more information.)
• {{ LANGUAGE_BIDI }} is the current language’s writing system. If True, it’s a right-to-left language (e.g., Hebrew, Arabic). If False, it’s a left-to-right language (e.g., English, French, German).

You can also load these values using template tags:

{% load i18n %}
{% get_current_language as LANGUAGE_CODE %}
{% get_available_languages as LANGUAGES %}
{% get_current_language_bidi as LANGUAGE_BIDI %}

Translation hooks are also available within any template block tag that accepts constant strings. In those cases, just use _() syntax to specify a translation string, for example:

{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}

In this case, both the tag and the filter will see the already-translated string (i.e., the string is translated before being passed to the tag handler functions), so they don’t need to be aware of translations.

Creating Language Files

Once you’ve tagged your strings for later translation, you need to write (or obtain) the language translations themselves. In this section we explain how that works.

bin/make-messages.py -l de

_("Welcome to my site.")

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

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."

make-messages.py -a

bin/compile-messages.py

How Django Discovers Language Preference

Once you’ve prepared your translations — or, if you just want to use the translations that are included with Django — you’ll just need to activate translation for your application.

Behind the scenes, Django has a very flexible model of deciding which language should be used — installation-wide, for a particular user, or both.

To set an installation-wide language preference, set LANGUAGE_CODE in your settings file. Django uses this language as the default translation — the final attempt if no other translator finds a translation.

If all you want to do is run Django with your native language, and a language file is available for your language, simply set LANGUAGE_CODE.

If you want to let each individual user specify the language he or she prefers, use LocaleMiddleware. LocaleMiddleware enables language selection based on data from the request. It customizes content for each user.

To use LocaleMiddleware, add 'django.middleware.locale.LocaleMiddleware' to your MIDDLEWARE_CLASSES setting. Because middleware order matters, you should follow these guidelines:

• Make sure it’s among the first middleware classes installed.
• It should come after SessionMiddleware, because LocaleMiddleware makes use of session data.
• If you use CacheMiddleware, put LocaleMiddleware after it (otherwise users could get cached content from the wrong locale).

For example, your MIDDLEWARE_CLASSES might look like this:

MIDDLEWARE_CLASSES = (
   'django.middleware.common.CommonMiddleware',
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware'
)

LocaleMiddleware tries to determine the user’s language preference by following this algorithm:

• First, it looks for a django_language key in the current user’s session.
• Failing that, it looks for a cookie called django_language.
• Failing that, it looks at the Accept-Language HTTP header. This header is sent by your browser and tells the server which language(s) you prefer, in order of priority. Django tries each language in the header until it finds one with available translations.
• Failing that, it uses the global LANGUAGE_CODE setting.

In each of these places, the language preference is expected to be in the standard language format, as a string. For example, Brazilian Portuguese is pt-br. If a base language is available but the sub-language specified is not, Django uses the base language. For example, if a user specifies de-at (Austrian German) but Django only has de available, Django uses de.

Only languages listed in the LANGUAGES setting can be selected. If you want to restrict the language selection to a subset of provided languages (because your application doesn’t provide all those languages), set your LANGUAGES setting to a list of languages, for example:

LANGUAGES = (
    ('de', _('German')),
    ('en', _('English')),
)

This example restricts languages that are available for automatic selection to German and English (and any sub-language, like de-ch or en-us).

If you define a custom LANGUAGES, it’s OK to mark the languages as translation strings — but use a “dummy” gettext() function, not the one in django.utils.translation. You should never import django.utils.translation from within your settings file, because that module itself depends on the settings, and that would cause a circular import.

The solution is to use a “dummy” gettext() function. Here’s a sample settings file:

_ = lambda s: s

LANGUAGES = (
      ('de', _('German')),
      ('en', _('English')),
)

With this arrangement, make-messages.py will still find and mark these strings for translation, but the translation won’t happen at runtime, so you’ll have to remember to wrap the languages in the real gettext() in any code that uses LANGUAGES at runtime.

The LocaleMiddleware can only select languages for which there is a Django-provided base translation. If you want to provide translations for your application that aren’t already in the set of translations in Django’s source tree, you’ll want to provide at least basic translations for that language. For example, Django uses technical message IDs to translate date formats and time formats — so you will need at least those translations for the system to work correctly.

A good starting point is to copy the English .po file and to translate at least the technical messages, and maybe the validator messages, too.

Technical message IDs are easily recognized; they’re all uppercase. You don’t translate the message ID as with other messages; rather, you provide the correct local variant on the provided English value. For example, with DATETIME_FORMAT (or DATE_FORMAT or TIME_FORMAT), this would be the format string that you want to use in your language. The format is identical to the format strings used by the now template tag.

Once LocaleMiddleware determines the user’s preference, it makes this preference available as request.LANGUAGE_CODE for each request object. Feel free to read this value in your view code. Here’s a simple example:

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian German.")
    else:
        return HttpResponse("You prefer to read another language.")

Note that, with static (i.e. without middleware) translation, the language is in settings.LANGUAGE_CODE, while with dynamic (middleware) translation, it’s in request.LANGUAGE_CODE.

The set_language Redirect View

As a convenience, Django comes with a view, django.views.i18n.set_language, that sets a user’s language preference and redirects back to the previous page.

Activate this view by adding the following line to your URLconf:

(r'^i18n/', include('django.conf.urls.i18n')),

(Note that this example makes the view available at /i18n/setlang/.)

The view expects to be called via the GET method, with a language parameter set in the query string. If session support is enabled, the view saves the language choice in the user’s session. Otherwise, it saves the language choice in a django_language cookie.

After setting the language choice, Django redirects the user, following this algorithm:

• Django looks for a next parameter in the query string.
• If that doesn’t exist or is empty, Django tries the URL in the Referer header.
• If that’s empty — say, if a user’s browser suppresses that header — then the user will be redirected to / (the site root) as a fallback.

Here’s example HTML template code:

<form action="/i18n/setlang/" method="get">
<input name="next" type="hidden" value="/next/page/" />
<select name="language">
{% for lang in LANGUAGES %}
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
{% endfor %}
</select>
<input type="submit" value="Go" />
</form>

Using Translations in Your Own Projects

Django looks for translations by following this algorithm:

• First, it looks for a locale directory in the application directory of the view that’s being called. If it finds a translation for the selected language, the translation will be installed.
• Next, it looks for a locale directory in the project directory. If it finds a translation, the translation will be installed.
• Finally, it checks the base translation in django/conf/locale.

This way, you can write applications that include their own translations, and you can override base translations in your project path. Or, you can just build a big project out of several applications and put all translations into one big project message file. The choice is yours.

All message file repositories are structured the same way:

• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• $PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• All paths listed in LOCALE_PATHS in your settings file are searched in that order for <language>/LC_MESSAGES/django.(po|mo)
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

To create message files, you use the same make-messages.py tool as with the Django message files. You only need to be in the right place — in the directory where either the conf/locale (in case of the source tree) or the locale/ (in case of application messages or project messages) directory is located. And you use the same compile-messages.py to produce the binary django.mo files that are used by gettext.

Application message files are a bit complicated to discover — they need the LocaleMiddleware. If you don’t use the middleware, only the Django message files and project message files will be processed.

Finally, you should give some thought to the structure of your translation files. If your applications need to be delivered to other users and will be used in other projects, you might want to use application-specific translations. But using application-specific translations and project translations could produce weird problems with make-messages. make-messages will traverse all directories below the current path and so might put message IDs into the project message file that are already in application message files.

The easiest way out is to store applications that are not part of the project (and so carry their own translations) outside the project tree. That way, make-messages on the project level will only translate strings that are connected to your explicit project and not strings that are distributed independently.

Translations and JavaScript

Adding translations to JavaScript poses some problems:

• JavaScript code doesn’t have access to a gettext implementation.
• JavaScript code doesn’t have access to .po or .mo files; they need to be delivered by the server.
• The translation catalogs for JavaScript should be kept as small as possible.

Django provides an integrated solution for these problems: it passes the translations into JavaScript, so you can call gettext and friends from within JavaScript.

js_info_dict = {
    'packages': ('your.app.package',),
}

urlpatterns = patterns('',
    (r'^jsi18n/$', 'django.views.i18n.javascript_catalog', js_info_dict),
)

urlpatterns = patterns('',
    (r'^jsi18n/(?P<packages>\S+?)/$, 'django.views.i18n.javascript_catalog'),
)

<script type="text/javascript" src="/path/to/jsi18n/"></script>

document.write(gettext('this is to be translated'));

d = {
    count: 10
};
s = interpolate(ngettext('this is %(count)s object', 'this are %(count)s objects', d.count), d);

s = interpolate(ngettext('this is %s object', 'this are %s objects', 11), [11]);

make-messages.py -d djangojs -l de

Notes for Users Familiar with gettext

If you know gettext, you might note these special things in the way Django does translation:

• The string domain is django or djangojs. The string domain is used to differentiate between different programs that store their data in a common message-file library (usually /usr/share/locale/). The django domain is used for Python and template translation strings, and is loaded into the global translation catalogs. The djangojs domain is only used for JavaScript translation catalogs to make sure that those are as small as possible.
• Django only uses gettext and gettext_noop. That’s because Django always uses DEFAULT_CHARSET strings internally. There isn’t much benefit to using ugettext, because you’ll always need to produce UTF-8 anyway.
• Django doesn’t use xgettext alone. It uses Python wrappers around xgettext and msgfmt. That’s mostly for convenience.

What’s Next?

This chapter mostly concludes our coverage of Django’s features. You should now know enough to start producing your own Django sites.

However, writing the code is only the first step in deploying a successful Web site. The next two chapters cover the things you’ll need to know if you want your site to survive in the real world. Chapter 19 discuses how you can secure your sites and your users from malicious attackers, and Chapter 20 details how to deploy a Django application onto one or many servers.