Django translation tutorial

Lately I've been working in a Django project where one of the requirements is that the users can choose their preferred language in the interface. In terms of implementation details, this means that most of the strings in the views, templates and even in the javascript code must be translatable. However, despite the Django documentation on internationalization and localization being fairly good and these features being supported for quite some time, I could not find any article or tutorial that shows how to implement translations in Django in a practical way.

In this tutorial series I will show how to set up translations in Django. Although we'll start this tutorial with a Django project from scratch, feel free to adapt and apply anything to your current working projects. I'm currently using Django 1.8.2 on Python 3.4.3, but this tutorial may be applicable for other versions.

Contents of this tutorial series:

1. Introduction
2. Settings and translation files
3. Templates and Javascript
4. Setting user language

Creating the Django app

In this post we will create a Django project that will be used in the following sections of the tutorial. For those who are already used to create and set up Django projects, you may want to download this zip file with the langtests project already set and skip the rest of this post.

For the others, before we start, please make sure that you have Django installed on your system. If you need instructions on how to setup and install Django, you may want to check the Django website or the Django download page.

To create the Django project from scratch, cd into a directory where you'd like to store your code and run the following command:

django-admin startproject langtests

This will create the langtests directory in the current working directory. To create the languages app, cd into langtests and execute:

python3 manage.py startapp languages

The directory structure of our project will be similar to the following:

langtests/
    manage.py
    langtests/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    languages/
        migrations/
        __init__.py
        admin.py
        models.py
        tests.py
        views.py

If you've worked with Django, you already know what these files are. If not, I recommend following the Django tutorial as it will allow you to understand most of the basic concepts.

Writing a view

Let's write a simple view for the index page of our 'languages' app. Open languages/views.py and put the following code in it:

from django.http import HttpResponse

def index(request):
    output = 'Welcome to my site.'
    return HttpResponse(output)

Now we need to map this view to a URL. Within the languages directory create a file called urls.py with the following contents:

from django.conf.urls import url
from . import views

urlpatterns = [
    url(r'^$', views.index, name='index'),
]

The final step is to map a URL from the root URLconf. In langtests/urls.py include the URLs for the languages app in urlpatterns as:

from django.conf.urls import include, url
from django.contrib import admin

urlpatterns = [
    url(r'^admin/', include(admin.site.urls)),
    url(r'^languages/', include('languages.urls')),
]

Now, to test the view, execute the Django server and point your browser to http://localhost:8000/languages/.

python3 manage.py runserver

If everything was correctly configured, you should see the following output on your browser.

This shows that the view is being correctly routed.