How To Manage Translations

Process for managing translations in CHT Core

Apps built with CHT Core are localized so that users can use them in the language of their choice. Languages supported by default are English, French, Nepali, Spanish, and Swahili. The goal of this doc is to help the community manage these and future translations.

Overview

Like the rest of the code the translation files live in the GitHub repo. These translation files are properties files, which are a series of keys and their corresponding values. The English file is used by default, and as such, it contains the entire set of keys. If any key is missing from another language file the English value is used.

Adding new languages

New languages must be added and configured in several places:

Create a new messages-xx.properties file in the api/resources/translations folder, replacing “xx” with the 2 or 3 letter language code.
Add the language to the LOCAL_NAME_MAP in api. Use the language code for the key, and the local name followed by the English name for the language in brackets, eg: “fr: ‘Français (French)’”.
Import the moment language pack in the main.ts file. If moment doesn’t provide the required language pack you may need to contribute it upstream to the moment library.

Adding new keys

First check if an appropriate key already exists in messages-en.properties. Using existing keys when possible reduces the effort required to translate the app into a new language.
Create a new key and default English value.
Reach out to the community to translate the value into all supported languages. The CI will block merging PRs unless all values are provided.
Validate the translations are complete and correct by executing npm run lint-translations.

Translating static text

In angular this is done using angular-translate, and ideally using the translate directive to reduce the number of watchers, eg: <h3 translate>date.incorrect.title</h3>.

Use the translation functions in the config module in API and Sentinel.

Translating configurations

Much of the app is configurable (eg: forms and schedules). Because the specifics of the configuration aren’t known during development time, these can’t be provided via messages. Instead configurers can provide a map of locale to value for each translated property. Then use the translateFrom filter to translate from the configured map using the user’s language.

Modifying any existing translation values

Update the default English value.
Reach out to the community to translate the value into all supported languages.
Validate the translations are complete and correct by executing npm run lint-translations.

Removing translation keys

Carefully verify that the translation key isn’t used. This can be challenging if keys have been concatenated or generated because then you won’t be able to find the complete string in the source code. Once this has been confirmed, then simply remove the key and value from all translation files.