How to Translate OpenMRS (Draft)

The primary objective of this documentation is to provide clear, comprehensive guidance for translation by community members and implementers of OpenMRS, for both contributing to and managing translations, ensuring that OpenMRS can be utilized in various languages to meet the growing global demand.

Overview

Importance of Localization for OpenMRS

Localization is crucial for OpenMRS for several reasons:

  • Increased Accessibility - Localization will make OpenMRS more accessible to non-English speaking users, expanding its reach and usability across different regions and cultures.

  • Improved User Experience - Users can interact with the software in their native language, which enhances their overall experience and efficiency in using the system. This is particularly important in healthcare settings where clarity and understanding are paramount.

  • Broader Adoption - As more regions can use OpenMRS in their local languages, the platform's adoption rates increase, leading to a larger, more diverse user base. This diversity can drive further improvements and innovations within the system.

  • Community Engagement - Providing resources for volunteers to contribute to translations promotes a sense of community and collaboration. Volunteers worldwide can contribute to the project, bringing in diverse perspectives and expertise.

  • Quality of Care - In healthcare, accurate communication is vital. Localized software helps ensure that medical records, patient information, and other critical data are understood correctly, reducing the risk of errors and improving the quality of care.

Who Should Translate?

Translation Volunteers

These individuals are proficient in English and at least one other local/native language and are interested in contributing to the localization of OpenMRS. They can range from community members, medical professionals, linguists, or anyone passionate about improving healthcare accessibility through better localization of the OpenMRS platform.

You can translate as much as you want, when you want. It’s only a matter of how much time and energy you are willing to invest as a volunteer translator.

Motivation

  • Contribute to a global open-source healthcare initiative.

  • Improve the usability of OpenMRS for non-English speaking users.

  • Gain experience in translation and localization.

  • Collaborate with a diverse, international community.

Skills and Knowledge

  • Proficiency in English and one or more target languages.

  • Basic understanding of translation tools (e.g. Transifex) or willingness to learn.

  • Familiarity with medical terminology (helpful but not required).

  • Attention to detail and commitment to quality.

Remember we want you to enjoy contributing and not burn out or lose interest.

Implementers

These are individuals or teams responsible for deploying and customizing OpenMRS for specific healthcare settings. They may include business analysts, project managers, developers, and IT professionals who work on configuring, translating, and maintaining OpenMRS distributions.

Motivation

  • Ensure OpenMRS meets the linguistic and cultural needs of the local population.

  • Facilitate smoother adoption and use of OpenMRS in non-English speaking regions.

  • Provide comprehensive and accurate translations to improve user experience.

Skills and Knowledge

  • Have an understanding of the OpenMRS architecture.

  • Be familiar with internationalization (i18n) and localization (l10n) concepts.

  • Be able to work with translation tools.

  • Have an understanding and knowledge of healthcare and linguistic requirements of the implementation region.

Responsibilities

  • Configure and maintain translated versions of OpenMRS.

  • Coordinate with translators and review the translated strings.

  • Ensure accuracy and relevance in the translated strings.

  • Guide users/translators on how to use the localized OpenMRS system.

Current State of Localization

Localization involves translating the user interface, content, and metadata into different languages, allowing users to interact with the system in their preferred language. The current state of localization in OpenMRS is as follows:

  • OpenMRS supports the translation of various UI components and metadata. However, this varies across different languages.

  • Currently, OpenMRS has integrated automated translation tools on the site openmrs.org and automated SEO results of the website in multiple languages.

  • The currently available translations are primarily driven by volunteer contributors with the help of this guide that highlights how one can get started.

Even though efforts have been put in place to help with translation efforts, there are still gaps and a need for clear documentation and guidance.

Existing Translation Infrastructure

The translation flow of OpenMRS consists of several tools and resources designed to help the localization process.

  1. Transifex

    • This is the main tool used for managing the translation flow of OpenMRS. It provides a collaborative environment where volunteers can contribute translations, review peer submissions, and ensure quality contributions.

    • It gives a clear-to-follow and easy UI for the translators.

    • The platform is integrated with OpenMRS, allowing real-time synchronization of translated strings to the main application.

  2. Auto-Translation Tools

    • With the help of automation tools such as Discourse Translator, the website can now be translated into different languages. This improves the SEO and attracts more non-English speaking users and translators.

  3. Documentation and Guides

  4. Community and Forums

    • The forum, also called Talk, serves as a platform for discussion and support, where community members can seek help, share experiences, and collaborate on translation projects.

    • In addition to having the forum as a general chat place, threads are tagged with “translation” which provides updates related to translation efforts.

Guidance for Translation Volunteers

Overview of Transifex

It’s our dream to provide a platform that can be used by anyone no matter the language they speak. To help us with this massive effort, we have integrated our open-source codebase with Trasifex - A tool to help us localize our codebase.

The translation workflow is split into three main sources:

  • Backend translation strings

  • Frontend translation strings

  • The concept dictionary

The first two sources are technical as they are built into the back or frontend but still provide localization keys and translation strings. The translation of these sources is automatically synchronized from Trasifex such that when new strings are added, they appear on relevant frontend and backend modules.

As a translator, you can sign up on our translation platform and contribute translations in any of the 50+ languages enabled there.

Getting Started

If you have not contributed to our translations before, you will need to create an account. Head over to the Transifex using this link: https://www.transifex.com/openmrs/. Click on "Sign Up" to create a new account if you don't already have one.

After you finish the sign-up process using the link provided, you will be directed to the OpenMRS project but in case you did choose to sign-up directly on the Transifex site, search for the "OpenMRS" project, Click on the project, and then click "Join Team" to request access. Once approved, your landing page should look like the one below.

screenshot-app.transifex.com-2024.07.02-13_05_31.png

Explore the available languages and modules that need translation while at the same time familiarizing yourself with the project layout and the translation interface.

Select a Project and Resource

Once on the homepage, you should see multiple “resources” available for translation.

screenshot-app.transifex.com-2024.07.02-13_18_52.png

All of these projects contain files that need translation and on the main dashboard as shown in the screenshot above you can see the progress of each project. Select any project you want to contribute to, and you will see a list of available languages for translation.

Select the language you want to work on, and you will see all the resources under that project that need to be translated. Transifex provides different ways of selecting a language that you can translate. The first option is via the Dashboard, where you select a resource and a language you want to work on and it will open up as shown below.

The second option is via the resource file itself. On the left panel, Select the Editor option, and a window will open that will require you to first select a project followed by a resource file and a language you would like to translate it to.

Each resource will show a progress bar. The Blue portion of the progress bar indicates what percentage of the resource has been reviewed, while the Light Sea Green portion of the progress bar indicates what percentage of the resource has been awaiting review, and the Grey part indicates what has not been translated yet.

In the case that your language isn’t listed, you get the opportunity to request for it to be added using an option provided at the bottom of each resource page.

Select a resource to work on and Transifix will open the editor view.

Translate Project

Transifex opens a source file into translatable “text”, usually in a sentence or word form. Each text is translated individually as seen in the image above.

  1. Shows a list of all strings both translated and untranslated.

  2. Shows the number of untranslated strings only.

  3. Shows a list of the translated strings that are yet to be reviewed/approved.

  4. This shows the strings tab that is free to be selected by translators under this particular project.

  5. This is the editor pane, that shows the selected string to be translated.

  6. This is the editor pane, where you may write your proposed translation for the selected string.

  7. This button allows you to save the proposed translation.

  8. A new feature in the editor that allows you to use AI to enhance the translations of the strings.

  9. If a different contributor has proposed a translation to a string, Transifex will display those proposals here. You will not be able to save an identical translation rather it will be highlighted as Used - instead, if a translation is accurate and hasn’t been used yet it will allow you to copy and use it.

  10. This overview “pane” button will hide the right side of the page and right.

The editor pane has a lot of functionality in it but what has been highlighted here is just an overview of the main parts that will make translation easier for you.

Once you are done making a contribution and have clicked the save button, the translation will be stored on Transifex. Other contributors will then be able to use your translation which will be stored under the suggestion tab and reviewers will be able to approve it if it’s correctly translated.

Feel free to translate as many strings as you wish. There are no extra steps needed after you complete translating a source file or suggesting a new translation. Simply click the Save button to store your translation.

Tips for Better Translation

  • Make use of the translation memory to see suggestions based on previous translations.

  • Refer to the glossary for standardized terms and phrases to ensure consistency across translations.

Note After translating a string and saving it, it is automatically submitted for review and also open to be used by other translators.

Reviewing and Approving Translations

Reviewing ensures there’s accuracy consistency and quality of the translated strings. The reviewing process is manually done and hence requires a set of eyes to catch incontinence and errors, suggest improvements, and approve the correct translations.

There isn’t that much difference between the translator's page and the reviewer's page. The only visible difference is the accessibility of the review functionality.

As a reviewer, your focus should be drawn to the Unreviewed tab and the Reviewe button if everything is correctly translated. In case there’s a wrong translation you can edit the available suggestion save the changes and review them at the same time.

As a reviewer, you can still get all the translations approved at a go using the Bulk review feature. Select all strings by clicking at the top checkbox (highlighted with the blue square on the image below), then Mark selected translations as Reviewed, and click Apply.

Tips for Better Reviewing

  • Be sure you are on the Unreviewed tab.

  • Read both the original string and the translated string carefully.

  • Compare the translation with the context and any provided comments.

  • Pay attention to details and ensure the translation accurately reflects the original meaning.

  • If improvements are needed, leave constructive comments and suggestions for the translator.

Guidance for Implementers

Implementation Process

Implementing OpenMRS in a non-English language environment involves a series of steps to ensure that the software is fully localized and functional for end-users. This section provides an overview of the key stages in the implementation process, highlighting essential tasks and best practices for achieving successful localization.

  1. Assessing Localization Needs

    • Identify Target Languages -

  2. Setting Up the Translation Environment

    •  

  3.