A Quick Guide to Django i18n

Learn how to easily do translation and localization in Django, the popular Python web framework.

Translating your web application to different languages and adding proper localization is something we all should do! This tutorial will give you a short introduction on how to get started with the Django localization process. Part of this can be easily applied to general Python localization and we also show you how you can speed up your i18n workflow even more by using PhraseApp.

We assume, that you have a working Django application and that you have installed gettext (for example via pip install gettext). If you havn’t used Django before, you maybe want to take a look at the official tutorial first and come back later.

Basic Setup

So let’s suppose you have a Django project called mysite and an application called polls. The structure of your project should be looking something like

The first step is to make sure that you have activated internationalization in your configuration. To do this, you have to make the following changes to mysite/settings.py:

Internationalize Templates

Then you have to mark all strings which have to be translated. Suppose you have the following template file polls/templates/polls/index.html

This file needs to be adapted to look like this

so we import the localization package and replace all texts with trans 'SomeTranslationKeyName'. Alternatively, you can use the default translation text as the translation key. This way, you will always have a good default text, if there is no translation available for the peticular key.

Internationalize Inside Python Code

When you want to localize strings within your python code (for example inside polls/views.py), you need to import the ugettext function. It is normal to alias it to _. So a simple localized view function would look like this

Create Translation Files

Now we have to create the translation files for every locale, we want to support. To do this create the directory polls/locale and inside the directory polls run

where you can replace de with the locale code of the language you like to add. In our example, this command will create the gettext file polls/locale/de/LC_MESSAGES/django.po with the content

and you can fill in the translations:

When you have finished translating, you have to compile everything by running

again inside the directory polls.

To quickly check that your translations work, you have to change the language code inside mysite/settings.py like so

When you open the polls application inside the browser, it should now be translated to German.

Speed up your process using PhraseApp

If you are using PhraseApp to manage your translations, you actually don’t need to manually create and edit the *.po files! You just have to create and translate the keys WelcomeHeading and WelcomeMessage within PhraseApp and use the export function to download your *.po files.

If you have installed our command line tool, the PhraseApp Client, your workflow is even simpler. Just create a configuration file .phraseapp.yml within your project’s root directory with the following content:

Then running

in the root directory of your project will update all translations in your project.

By the way, using our In-Context Editor within your Django application is also really simple! You only need to install django-phrase with pip:

Then just change all templates you like to use the In-Context-Editor on, in the following way

Note: it is important to load phrase_i18n after i18n.

Finally add the following lines to your configuration and you are ready to go!

Select Locales

One usually wants to select the locale according to the user’s browser settings. In order to do this you have to change the mysite/settings.py file to the following

This way, if the user has German as their locale, they will see the de translations. Otherwise, the default locale will be en-us. You can check that this is working properly with curl:

which should return something like this

Further Reading

If you want to learn more about internationalization in Django, take a look at the official documentation. There is also another nice article.

If you want to learn more on how you can setup the PhraseApp In-Context-Editor within your Django application, take a look at the documentation at PhraseApp. You can also find the full sources of the demo application we used in this tutorial on github.

Also, if you are using Flask, we have another blog post introducing you to localization in this framework.

Comments