Documentation on How to Translate OpenMRS

  • Project Owner: Hillary Nyakundi

  • Primary Mentor: @Grace Potma

Primary Objective

Clear documentation for translators and for implementers to quickly understand how to translate OpenMRS.

Project Description

The demand to robustly localize OpenMRS is growing. The OpenMRS application is highly localizable, and a significant foundation of translation infrastructure is already built-in: but ironically, this is not well-known, and neither the small amounts of volunteer translation nor the infrequent peer-review of strings match the growing needs of OpenMRS translation.

Since turning on tooling to auto-translate our website and SEO results, we have seen signs of greater interest in translating OpenMRS. Now, through this project, we would like to mend two large gaps in documentation about how to translate OpenMRS:

  1. Gap #1: Guidance for Translation Volunteers: There is minimal guidance on how volunteer contributors proficient in both English and other languages can contribute translations.

  2. Gap #2: Guidance for Implementers: There is inadequate organized, clear guidance in one place on how implementers (both BAs/PMs or Developers) can translate their distribution entirely into one or more other languages (other than English). The good news is, OpenMRS is in fact highly i18n-izeable, and experienced implementers are already using completely translated distributions in many languages in production. There’s also no guide that Implementer leaders can hand over to contracted translators (e.g. “As an Implementer launching OpenMRS in a non-English language, I need a guide we can give to translators who will be translating our distribution, on how exactly they can do that.” Ideally the Guidance for Translation Volunteers could be re-useable in this instance )

Both of these guides should be a reusable asset relevant to any kind of language, feature, or content area, and we expect this will be leveraged for years to come.


  1. Documentation to support a stronger Translation Community for OpenMRS

    1. Summary of Research: Work with potential Translators in understanding what information and support they need in order to perform accurate and effective translations of the OpenMRS interface and metadata content. Create a summary document of understanding of needs from calls with Translators

    2. Translator Guide: Create clear documentation across OpenMRS artifacts on how to contribute and peer-review translations. OpenMRS website page recruiting translation contributors and published Translation Guide for new translators, including a guideline for conducting Peer Review of submitted translations contributed by someone else to ensure quality and safety.

  2. Documentation on How-To-Translate-your-OpenMRS-Distro

What Has Already Been Done

Existing Resources To Leverage in this Project

SME to Possibly Interview:

  • Ian Bacher

  • Romain Buisson


Miscellaneous Things to Include in the Translation Documentation

Gotcha's Grace Recommends That We Remember To Document for Translators:

  • For “Location”, use “emplacement” instead of “site”, since “Site” can be used differently than “Location”

  • Visit = / = Encounter

  • Check-in = / = Register (so would maybe not want to use “Enregistrer” for Check-in)

  • Be careful in editing mode to double-check that the language you are translating for is correct. When you change the repo/source you are translating for, this sometimes changes sneakily!!

    • image-20240607-225325.png

On updating translations in modules

Most modules have a GitHub Action that is scheduled to run every day at 8PM UTC which pulls in the translations from Transifex and updates the source files in the repository and creates a PR/updates an existing PR.
There is another GitHub Action that is triggered whenever a push is made to the main branch which handles updating Transifex with new translation keywords, if any.