The first thing that we want to do is translate all the static content on our site. This includes all the headlines, links, and form labels that you have seen in the preceding three screens. To translate strings that are used in templates, Django provides us with a trans template tag. Let's take a look at how to use it first in a simple context, and then I'll go into the details of how it works. This is a slightly long section as we will do a lot of things here that make up the foundation of the translation feature of Django.

Open up main/templates/movies_list.html, and replace Movies List in the h2 tag with the following:

{% trans "Movies List" %}

Add the following load tag to the second line of the file, right after the extends tag:

{% load i18n %}

That's all the changes that we need to make to the template for now. I'll be explaining what these two lines do in just a little bit, but first I want to complete the whole translation process so that you can look at the whole thing instead of just smaller parts.

Next, let's run this command from the project root:

> python manage.py makemessages -l fr
CommandError: Unable to find a locale path to store translations for file main/__init__.py

If you run this command, you should also see the same error as I did, something being unable to find a locale path. We'll explain what the locale path is after we're done with the demo. For now, create a new folder called locale in the main folder and run the command again:

>mkdir main/locale
> python manage.py makemessages -l fr
processing locale fr

This time the command succeeds. If you look in the locale folder that you created, you should see that a whole new hierarchy of folders has been created underneath it. What the makemessages command did was create a django.po at main/locale/fr/ LC_MESSAGES/django.po file. If you open this file, you should be able to figure out a bit about its purpose. The last three lines of the file should be as follows:

#: main/templates/movies_list.html:5
msgid "Movies List"
msgstr ""

Together with the path of this file (locale/fr/LC_MESSAGES/django.po) and these three lines, you should be getting the idea that this file will contain the translated French text for the string that we marked earlier with the trans tag. Anything you put in quotes next to msgstr is what will replace the original string in the French translation of the site.

I used Google Translate to translate the Movies List string, and it gave me the translation as Liste des films. Put this translation in the quotes next to msgstr. The last three lines of the django.po file should now match the following:

#: main/templates/movies_list.html:5
msgid "Movies List"
msgstr "Liste des films"

Next, run this command from the project root:

> python manage.py compilemessages -l fr
processing file django.po in /Users/asadjb/Programming/Personal/DjangoBluePrints/mmdb/mmdb/main/locale/fr/LC_MESSAGES

If you were to look in the LC_MESSAGES folder now, you should see that a new django.mo file has been created. This is the compiled version of our django.po file, the one that we put the translated strings into. For performance, Django translations require the file to be compiled into a binary format before it can pick up translations for strings.

Next, open up mmdb/settings.py and find the MIDDLEWARE_CLASSES list. Edit it so that the django.middleware.locale.LocaleMiddleware string appears between the already installed SessionMiddleware and CommonMiddleware. The position is important. The list should now look as follows:

MIDDLEWARE_CLASSES = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.auth.middleware.SessionAuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

Next, add a LANGUAGES variable to the settings file and give it the following value:

LANGUAGES = (
    ('en', 'English'),
    ('fr', 'French')
)

By default, Django supports a much longer list of languages. For our project, we want to restrict the user to only these two options. That is what the LANGUAGES list does.

The last step is to modify the mmdb/urls.py file. First, import i18n_patterns from django.conf.urls.i18n. Next, change the urlpatterns variable so that the i18n_patterns function wraps all our URL definitions, as shown in the following code:

urlpatterns = i18n_patterns(
url(r'^$', MoviesListView.as_view(), name='movies-list'),
url(r'^movie/(?P<pk>d+)/$', MovieDetailsView.as_view(), name='movie-details'),
url(r'^movie/(?P<movie_pk>d+)/review/$', NewReviewView.as_view(), name='new-review'),

url(r'^admin/', admin.site.urls),
)

With this done, let's test and see what our hard work got us. First, open up http://127.0.0.1:8000. You should see the same home page as before, but if you pay attention to the address bar, you will notice that the browser is at http://127.0.0.1:8000/en/ instead of what we entered. We will look at the details of why this happens next, but in a nutshell, we opened the home page without specifying a language and Django redirected us to the default language for the site, which we specified earlier as English.

Change the URL to http://127.0.0.1:8000/fr/ and you should see the same home page again, but this time, the Movies List text should be replaced by what we said was its French translation, as shown in the following screenshot:

While all of this probably seems like a lot of work to translate a single sentence, remember that you only need to do this once. Let's see how easy it is to translate something else now that the foundation is there. Let's translate the word Stars to its French translation, Etoiles. Open up main/templates/movies_list.html and replace the word Stars with the following:

{% trans "Stars" %}

Next, run the makemessages command:

> python manage.py makemessages -l fr

Open the main/locale/fr/LC_MESSAGES/django.po file. You should see a new section for the Stars string that we marked for translation. Add the translation (Étoile) and save the file. Finally, run the compilemessages command:

> python manage.py compilemessages

Open the French language home page again by visiting http://127.0.0.1:8000/fr/. You will see that the word Stars has been replaced by its French translation. The effort involved was minimal. The workflow that you just followed: marking one or more strings for translation, making messages, translating the new strings, and finally running compilemessages is one followed by most Django developers when they are translating a project. Most of the effort involved with getting a site translation ready is all the work that we did beforehand. Let's take a closer look at what exactly we have done to get our web application translatable.