How To Translate the OpenMRS Platform and Modules
- Ben Wolfe
- Daniel Kayiwa
- Andrew Kanter
If you are a user of OpenMRS, and want to change the current language of your installation to another available language, see the Localization page.
This page is out of date
 See Translating the Reference Application instead.
Current status of translations
The current state of the i18n files in OpenMRS releases:
Where to find the files
OpenMRS Platform
The most up-to-date file is the English messages.properties file in the trunk folder of the OpenMRS Platform source code. You can download that file from our latest master branch here:
Other language translations are available in the WEB-INF directory, along with messages.properties. They are named with the 2-letter ISO 639-1 language code, such as messages_es.properties, messages_it.properties, etc. View them in our source code repository here:
If you have already installed OpenMRS, extract the api jar file for the messages.properties file.
Modules
Each module might have a different location for the messages.properties file.  Two of the more common locations are in the resources or metadata folder within the module code. One example is the reporting compatibility module where the files are located at trunk/omod/src/main/resources/
Step One: Adding or updating a translated language
Adding a new language
This is relatively easy. After downloading or saving messages.properties, rename a copy of it to your new language:
messages_xx.properties
where the "xx" is replaced with the two-letter, lowercase code from ISO 639-1.  Edit the file and modify all the phrases or words on the right side of the equals (=) sign to the new language. The left side of each line (left of the equals sign) must remain the same – they are needed by the system. You need to save the file as UTF-8 with BOM and leave the first line empty.
Put this new file into the WEB-INF folder of your OpenMRS installation and edit the locale.allowed.list global property in the OpenMRS administration section to list this new language code. You can now switch to that locale at the bottom of any OpenMRS page. If you cannot, then you need to restart OpenMRS.
Adding a new country locale within an existing language
This is if you want to specify a country for your language file. For example, US english would be messages_en_US.properties, or Chilean spanish would be messages_es_CL.properties. For this the best thing to do is to just have the country specific customizations in that file.
Updating or improving an existing language
Updates to messages.properties happen sometimes, so some lines in the file might disappear or be modified.
If you are updating a language, you will need to find all items from the English messages.properties file that are not in the your language's messages_xx.properties file and translate them. You can see below for tools to help you with this.
For OpenMRS trunk, put this new file into the WEB-INF folder of your OpenMRS installation. You should also save the file to a secure backup location--if you re-install OpenMRS, your updated file will not remain.
For OpenMRS modules, you will need to compile the module with this new file or submit it to the module's programmer for them to compile it with the new file.
Step Two: Submitting the files to OpenMRS (Please do this so that everyone gets the translation)
Create a new TRUNK issue in JIRA, our issue tracking system, and attach your modified messages.properties or new messages_xx.properties file. Explain what changes or the new language that you've added. Someone will review your updates or additions for inclusion in an upcoming OpenMRS release.
Helpful tools to use for translation
Custom Messaging module
Probably the most user friendly way to translate OpenMRS is to use the Custom Messages module. It supports user-defined, live translations of OpenMRS and its modules right when viewing the pages.
Database Messaging module
One way to translate OpenMRS is to use the Database Messaging module. As of October 2011, the main limitation was that you couldn’t easily see which of the messages were not translated in a specific locale.
Eclipse
Another way is to use Eclipse and its ResourceBundle Editor plugin. Download the plugin here. The limitation to this method is that you have to download the source code for the program (e.g., OpenMRS) you want to translate.
After downloading the plugin, extract the plugins to the Eclipse plugin directory, such as C:\eclipse\plugins.
Restart Eclipse and set the default program to open *.properties files to the resource bundle. Go to Window -> Preferences, in File Associations click Add, in the File Type, place *.properties and click OK.
Then in the File types: box click on the *.properties File Type and in the Associated editors:, click on ResourceBundle Editor, and then click on the Default button.
To use the editor, go to the properties file that you want to translate in your module or core (either by finding it within the project that you’ve downloaded into Eclipse or by doing the search command within Eclipse). Once you double click on the file, it will bring up the boxes where you can edit the different languages for that message.
Translating OpenMRS clinical terminology
The messages.properties file handles application-specific language. For more information about updating and translating clinical terminology used in OpenMRS, see Terminology Service Bureau.