Configure O3 Your Way
Configure Translations in O3

How to Configure Translations in O3

There are several categories translations live in within our software project:

  • in Code: We use a tool called Transifex (opens in a new tab) to automatically extract hard-coded words (e.g. "Click Here"), translate them in the Transifex UI, and contribute those translations back to the O3 RefApp.
  • in Forms
  • in Terminology: e.g. the CIEL code 121375 for Asthma has multiple existing translations attached to it (as you can see here (opens in a new tab)). If you were using that code and wanted a new language option, you would need that added as metadata on this concept.

Using Transifex

How to Translate OpenMRS Frontend Coded Elements via Transifex

You can find the OpenMRS Transifex tutorial here (opens in a new tab). Questions or feedback on this Tutorial can be shared in this Talk Forum thread (opens in a new tab).

Guidance on using Transifex for older OpenMRS Modules (OMODs) can be found here (opens in a new tab). Tips on Transifex integration with OpenMRS repos in general are also discussed here (opens in a new tab).

How to Ingest App String Content from Transifex into the O3 RefApp

Summary: The translation files will have to be pulled from Transifex and committed into the code directly, for each repo.

  • Step 1: Transifex Setup: Ensure the O3 repos you need are included in the OpenMRS Org Transifex project 4 (e.g. you can see esm-patient-management is here 1, esm-patient-chart is here 1, etc)

  • Step 2: Complete Translation in Transifex UI: Ensure your translation team goes through the UI to translate each repo’s strings (see the UI guide above).

  • Step 3: Manual, Simple Workflow to Export JSON from Transifex and Upload to O3:

    • Export JSON from Transifex: In the left navigation, click Resources for the Repo, then click the language you want, and click “Download for use” from the Resources modal that popped up. This downloads a JSON file for you.

      Transifex Modal to Download a JSON Export
    • Upload JSON into the repo’s esm-NAME-app/translations/ directory: E.g. this example (opens in a new tab) of JSON string translations uploaded for the active visits app.

    • Then: The strings should be translated in the UI when the user switches their locale.

      Locale Switcher UI
  • Alternative to Step 3: Automated Workflow: This can also be done by using the CLI Transifex client (opens in a new tab) and running tx pull -l fr (to get the fr locale for instance) and commit the changes.

Translation Overrides Specific to an Individual O3 Module

You can use the configuration system to provide localised translations for O3 components. This is useful if, for example, you want to change the label on a button or rename a link. This should not be used to translate components into a new locale. Instead, please help us out by adding those translations directly to the RefApp using Transifex (opens in a new tab).

For example, if you wanted to rename the "Start a Visit " action on the patient chart, you can use this configuration:

  "@openmrs/esm-patient-chart-app": {
    "Translation overrides": {
      "en": {
        "startVisit": "Check-in"

Translation overrides, like this, can be provided at any level of configuration, including the configuration for a particular slot or an extension in a slot. Note that the string "Translation overrides" must be in exactly that case, the key, like "en" should be the locale you want to override the translation for and the translation key, e.g., "startVisit" should match what is in the translation file for the locale you want to override. Multiple languages can be specified by having multiple keys, e.g., "en" and "fr" would allow you to override the text in both English and French.