Translating your site with Django 1.8

3 min readOct 3, 2015

Last week I started using Django’s Internationalization features to translate one of my side projects into French. Although the Django docs on the subject are great, their thoroughness made getting things started a bit of a challenge. Now that I’ve got things working, I’m going to share a short introduction to translating your site with Django.

This is by no means a comprehensive tutorial. For more information on Internationalization and Localization, check the Django Translation Docs.

Configuring your Settings

Before we start translating the site, we need to tell Django to look for the user’s language preferences, which languages we support, what the default language is, and where it should look for the translation files we provide. All of this is done in our settings.py file.

from django.utils.translation import ugettext_lazy as _# The LocaleMiddleware check's the incoming request for the 
# user's preferred language settings. Add the LocaleMiddleware
# after SessionMiddleware and CacheMiddleware, and before the 
# CommonMiddleware.
MIDDLEWARE_CLASSES = (
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
)# Provide a lists of languages which your site supports.
LANGUAGES = (
    ('en', _('English')),
    ('fr', _('French')),
)# Set the default language for your site.
LANGUAGE_CODE = 'en'# Tell Django where the project's translation files should be.
LOCALE_PATHS = (
    os.path.join(BASE_DIR, 'locale'),
)

Note that when LocaleMiddleware determines the language settings, a logged out user’s browser settings take priority, whereas a logged in user’s site language preferences take priority. For more information on how this works, see How Django Discover’s Language Preference.

Templates

At this point Django should be configured to determine the user’s language and look for translations. Let’s say we’re looking to translate a simple Log in page with a template that looks like something like this:

<h1>Log in</h1><label>Username</label>
<input id='password' type='text'/><label>Password</label>
<input id='password' type='password'/>

Django provides some template tags to translate your page. To give your template access to these tags, put {% load i18n %} at the top of the file. This needs to be added to every template that uses these tags, even if they extend a file that already has them.

There are two i18n template tags–trans and blocktrans–but I’ll just be discussing the trans tag in this tutorial. To translate a piece of text, we simple put that text inside quotes in the trans tag. Once we do this to all the text, our Login template will look like so:

# Loads the D
{% load i18n %}
<h1>{% trans 'Log in' %}</h1><label>{% trans 'Username' %}</label>
<input id='password' type='text'/><label>{% trans 'Password' %}</label>
<input id='password' type='password'/>

For information on the advanced features when translating templates, see the Internationalization: in template code article in the Django docs.

Making the Translation Files

Now that we’ve wrapped our text in `trans` tags, we’ll create the translation files. From the command-line in project directory, run the following command:

> python manage.py makemessages -l 'fr'

This will find all the places in your project where translation might occur, and creates a .po file inside locale.

myproject/
    myproject/
    templates/
        login.html
    locale/
        fr/
            LOCALE_MESSAGES/
                django.mo

Take a look at the django.po

#: login.html:2
msgid "Log in"
msgstr ""#: login.html:4
msgid "Username"
msgstr ""#: login.html:7
msgid "Password"
msgstr ""

After you replace the msgstr with your translation, the file should look like this:

#: login.html:2
msgid "Log in"
msgstr "Connexion"#: login.html:4
msgid "Username"
msgstr "Nom d'utilisateur"#: login.html:7
msgid "Password"
msgstr "Mot de passe"

Note that if a msgstr is not provided for a language then the msgid will be used instead. Since we haven’t even provided a .mo file for english, the msgid will be used instead.

Compile your Translations

The last thing we need to do in order for Django to translate your site, is compile the .po into .mo files. Once again open up the command-line in your directory, and run the following:

> python manage.py compilemessages

You should now see a .mo file alongside your .po file!

Log into your (French) Site!

With the settings configured, your templates tagged, and the translation files compiled, the site should now be rendered in French!

If everything’s still in English, remember that a Logged out user’s browser settings take first priority. You may have to change your settings to see translation. Here’s how you do it in Chrome, Firefox, and Safari.