Internationalization

Translation Files ¶

Translations are stored in simple JSON files. This is a mapping table where the key is a unique ID or an English string.

{
    "menu.unread": "Non lus",
    "entry.status.unread": "Non lu",
    "This feed already exists (%s)": "Cet abonnement existe déjà (%s)",
    "time_elapsed.minutes": [
        "il y a %d minute",
        "il y a %d minutes"
    ]
}

• Translation keys with unique IDs allow you to provide different translations according to the context.
• Translation keys with English text are mostly used for internal errors. The English text is used to display the error in logs and API responses, while the translation is used for the user interface.
• Placeholders are used by the Golang package fmt.

Plural Forms ¶

Some languages have different rules regarding plurals. These rules are defined in the file locale/plural.go. You could add more rules if yours is not available.

In the JSON file, a plural translation is defined like that:

{
    "page.feeds.error_count": [
        "%d error",
        "%d errors"
    ]
}

This example is for the English language, the plural form is plurals=2; plural=(n != 1);. For one error, we will have 1 error, for 2 or more errors: 3 errors.

You can find the different plural forms here:

• https://localization-guide.readthedocs.io/en/latest/l10n/pluralforms.html
• http://www.unicode.org/cldr/charts/29/supplemental/language_plural_rules.html

How to add a new language? ¶

1) Checkout the source code from the repository

Clone the Git repository locally.

2) Create a new translation file

In the folder locale/translations, create a new JSON file, for example, de_DE.json for German. You could copy the translations from en_US.json and replace the strings.

3) Add the language to the list

Open the file locale/locale.go, and edit the function AvailableLanguages().

func AvailableLanguages() map[string]string {
    return map[string]string{
        "en_US": "English",
        "fr_FR": "Français",
        "de_DE": "Deutsch",
        "pl_PL": "Polski",
        "zh_CN": "简体中文",
        "nl_NL": "Nederlands",
        "ru_RU": "Русский",
    }
}

This function returns a mapping table of available languages. On the left, you have the language code and on the right the language name written in native language.

4) Test the translations

Translation files are embedded into the application executable. You must compile the software to see the changes.

make run

You must have a local development environment configured properly.

5) Create a branch and send a pull-request

Your pull-request should contains only 2 files:

• locale/translations/xx_XX.json
• locale/locale.go

If you don’t know how to send a pull-request, follow the GitHub documentation.

How to update a translation? ¶

Update the corresponding JSON file: locale/translations/xx_XX.json, and send a pull-request.

If you add new translation keys, keep in mind that all JSON files must be synchronized; otherwise, the unit tests won’t pass.

You can use Google Translate or a similar tool to update the translation files. Alternatively, you could use the English text as a reference for other translations. Sometimes, it might be preferable to have a proper translation done by a native speaker.