Localization

This page is a guide to add translations to the web portal.

The application's default language is English. The language menu appears in the top-right corner.

Languages drop down menu

Table of Content

Introduction

This project uses Flask-Babel to manage languages with the help of .po files. For more information, visit:

Getting started

Assuming you cloned the repository and change it to your working directory, run:

$ make l10n-compile

This will set multiple languages in the web portal.

Base template

The messages.pot file is needed to generate and update the other language files. If it does not exist yet, run:

$ make l10n-extract

⚠️ Run this command after any changes are made to the application's text in order to update the messages.pot file.

Updating the English base app

When changes to the application text content are made, whether in the HTML, JavaScript, or Python files, follow the steps below.

Recreate the base template file (messages.pot):

$ make l10n-extract

Update the localization files:

$ make l10n-update

Then, translate the updated parts in the .po files. Once done, compile them again:

$ make l10n-compile

Add a new language

To translate the application into a new language, find its ISO-639-1 two-letter code. For example, French code is fr.

Check whether the language folder exists already at piguard_portal/translations/<CODE> (the French folder would be named piguard_portal/translations/fr).

If it doesn't, create one with this command, replacing <CODE> with your language code:

$ pybabel init -i messages.pot -d piguard_portal/translations -l <CODE>

For example:

$ pybabel init -i messages.pot -d piguard_portal/translations -l fr

This command will create a folder with a LC_MESSAGES subfolder containing a messages.po file.

Translation

Look for a messages.po file in your desired language folder located in piguard_portal/translations. This is the file you need to translate or give to a translator.

For example, for French, the file is piguard_portal/translations/fr/LC_MESSAGES/messages.po.

Once translated, commit and push the updated file into the repository.

Integration

Once the files are translated, run:

$ make l10n-compile

This will compile .mo binary files used by the application. These files are not meant to be committed.

Notes to translators

RTL

For right-to-left languages (like Arabic), the application will automatically switch to right-to-left layout, just translate the file. However assets (e.g. images) per locale are not supported yet. If it is critical that some assets be replaced for a certain language, please report it.

HTML

The strings may contain HTML tags to emphasize parts of a text. For instance:

Key inserted <span class="%(classes)s">successfully</span>

The class and tag names should be unchanged.

In particular, make sure the double quotes around attributes are unchanged (" ASCII code 34). Some OS (like macOS) automatically change typed quotes to the language-specific ones (for example: French «», English “”). Beware of the curved quotation marks “”, which look like the correct one " but aren't.

💡 Read this to learn how to toggle smart quotes on macOS.

Correct:

Schlüssel <span class="%(classes)s">erfolgreich</span> eingefügt

Incorrect:

Schlüssel <span class=“%(classes)s”>erfolgreich</span> eingefügt