Translations (i18n) in Django

Internationalisation (or i18n for short) is the concept of adapting a website for another country, language or culture. It regroups the translations of text, but also the format of dates and hours for example.

Translating texts

• Django Documentation on Text Translation

1. Use the gettext method for all texts

In your code, use the gettext method to signal to django that the text should be translated:

from django.utils.translation import gettext as _

def my_view(request):
    output = (
      _("Welcome on Nantral Platform %(name)s!")
      % {'name': request.user.first_name}
    )
    return HttpResponse(output)

# returns "Welcome on Nantral Platform John!"

For texts that are NOT inside a function, you must use gettext_lazy instead of gettext:

# use gettext_lazy instead of gettext!
from django.utils.translation import gettext_lazy as _

class Group(models.Model):
    name = models.CharField(_("Group Name"))

Conventions

• In your code, write texts in English
• For other languages, like French, write the translations in the .po files (see the following section)

2. Write the Translations

First run: install gettext!!!

To use the django commands for translations, you have to install the gettext program.

Windows

The gettext utility is not really supported on Windows. You can refer to the django documentation, which proposes some alternatives. However, we strongly recommend you to use WSL instead, so as to run Nantral Platform in a Linux machine (in your Windows).

MacOS

Run this command:

brew install gettext

Linux

Run these commands:

sudo apt-get update
sudo apt-get install gettext

First, create or update the .po file:

• Go into the app where you want to add translations:

  cd apps/<app_name>
• Create or update the .po files for the French translations:

  pipenv run django-admin makemessages -l fr
• Open the .po file created in locale/fr/LC_MESSAGES, and fill in all the translations. You can also use a graphical editor, like Poedit.

3. Compile the translations

Once you have finished, it's time to compile the translations! Just run, in the backend directory:

pipenv run django compilemessages -l fr

tip

If you use Poedit, the compilation is automatically done when you save your modifications.

That's it! You can now run the website, and the translations should adapt to the selected language!

Translating dates

You can translate dates using the django.utils.formats module:

from django.utils import formats

formats.date_format(date, format='SHORT_DATE_FORMAT')

The available formats are:

• SHORT_DATE_FORMAT -> 01/01/2022
• SHORT_DATETIME_FORMAT -> 01/01/2022 12:00
• DATE_FORMAT -> January 1, 2022
• DATETIME_FORMAT -> January 1, 2022, 12:00
• TIME_FORMAT -> 12:00

Adding a new language

1. In the django settings, update the LANGUAGES key:
   config/settings/base.py

   LANGUAGES = [
      ('fr', "Français"),
      ('en', "English"),
      # your language here
   ]
2. Then create all the new .po files for each app:

   cd apps/<app_name>
   pipenv run django-admin makemessages -l <your_language_code>
3. Write all the translations, and finally compile them:

   pipenv run django compilemessages -l <you_language_code>
4. Add the language to the frontend (see Frontend i18n)

Congratulations 🥳 You added a new language!