Internationalization

Translation files

Translations are just a simple JSON file. This is a mapping table, the key could be 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 allows you to give a different translation 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, but the translation is used for the user interface.
  • Placeholders are the ones 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:

How to add a new language?

1) Checkout the source code from the repository

Fork the project, fetch the source code locally and add your fork as Git remote (Details).

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 fr_FR.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 3 files:

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

If you don’t know how to send a pull-request, here is the documentation of GitHub: https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request