Translation of the Workplace

In order to create a new translation, you have to be logged in as an Administrator or as a member of the Administrators group. Here you find the detailed description of the basic steps.

Localization in OpenCms

OpenCms uses the standard Java approach for localization: All localized labels, messages etc. are contained in a set of so-called message bundles. A message bundle is a set of message templates and their identifying keys. The message bundle is associated with a specifier which uniquely identifies the bundle.

Some examples of how entries in the properties files look like: 

GUI_LOGIN_HEADLINE_0             =Please Login
GUI_LOGIN_USERNAME_0             =User name:
GUI_LOGIN_PASSWORD_0             =Password:
ERR_SECURITY_LOGIN_FAILED_1      =OpenCms login of user "{0}" failed.
...

You will notice that some of the messages have parameters, which are enclosed by braces ({0}, {1}, ...). They are used to fill in arguments such as user- or filenames.

Translating the message bundles

To localize OpenCms, you have to translate these message-bundles to your language.

Important: You do not have to translate all keys of the properties file. If you leave out some key/value pairs, OpenCms uses the default english label for keys not present in your file from a default workplace.properties file.

The upper-case keys have a certain prefix indicating where this key will be used: Keys with a GUI-prefix and lowercase keys are the labels for the workplace. The keys starting with ERR are error messages, RPT the report messages. LOG are the log messages and thus not so important to translate.

For basically all languages, there exists a two-letter ISO country-code (e.g. it for Italian). Message bundles translated into Italian need to be put in files messages_it.properties . The message bundles have to be placed in the following location:

/system/workplace/locales/[your locale]/messages/[package path]/messages_[your locale].properties

To keep at the previous example, the italian translation of the bundle org.opencms.db.messages need to be placed in the file

/system/workplace/locales/it/messages/org/opencms/db/messages_it.properties

A convenient way to create and edit the new property files is to use the localization tool available in this module. It also helps you to get an overview of the existing message bundles.  Click here for a short description of the tool. Using the tool (or whatever you prefer) you can now start to translate all the key values in the properties file. The key names should be pretty self-explanatory.

You can get the last version of the english property files as base for the translation using the OpenCms web based CVS viewer at http://www.opencms.org/cvs/viewcvs.cgi/opencms/src/org/opencms/ . 

Create a new module for your localization

In order to make your localization availabe to the OpenCms community, create in the Administration view a new module for your locale. Please enter the following parameters:

• Package name: org.opencms.locale.it (".it" for Italian example locale, use the 2 letter ISO code for the language of your choice)
• Module name: Italian localization for the OpenCms workplace (for the Italian translation in our example)
• Description: This module contains the Italian language localization files for the OpenCms workplace. (Description for our example)
• Module group: OpenCms Localization
• Maintenance event class: [leave this empty] (default)
• Publish event class: [leave this empty] (default)
• Author: [insert your name or company name here]
• Email: [insert your email address here]
• Module parameter: [leave this empty] (default) 

As module resources, add each of your created .properties file under /system/workplace/locales/[your locale].

Finally, you have to add an export point, pointing from

/system/workplace/locales/[your locale]/messages/ toWEB-INF/classes/

Exporting the module

The last step is to export the localization module. To do so just switch to the "Adminstration" -> "Module management" screen again.

Click on the icon left to your module name and select "Export" and confirm with "Ok". Your module should now be exported. You might check if the property files are listed as exported in the output.

Confirm with "Ok" after the export is finished.

Now your module should have been written to {$TOMCAT_HOME}/opencms/WEB-INF/packages/modules, in our example with the filename org.opencms.locales.it_1.zip.

You can now import that module to other OpenCms servers by switching to the "Online" project in the OpenCms workplace on another server and selecting the "Upload module from" option on top of the screen.

Testing the new locale

Now let's say you have translated the property-files as described, and exported them as a language module. You can test your localization by importing the module.

After importing your module, let's check if the property files have been exported to the external location. Open a file browser on your hard disk and navigate to the
{$TOMCAT_HOME}/opencms/WEB-INF/classes
directory (or whatever else your installation path is). There should be a subffolder structure org/opencms/ and the property files you have created should be contained the subfolders of this directory.

The next step is a Tomcat restart. Unfortunatly Java is unable to re- read ResourceBundles after a change, and so you must start / stop your Java VM every time you have made changes to the locales if you want to see your changes in action.

After a restart of OpenCms you should log in and open the user perferences. The new locale you have just created should appear now at the "Startup options" tab. Select it to switch to your new locale.

Your translations should be shown now.

Congratulations, you have just created a localized OpenCms version.

Please contribute

Of course, it would be great if you contribute your translation so that others can use it as well. If you want to do so, please send your exported module to contributions@opencms.org. We will make it available for download on the OpenCms website. You (or your company) will of course be mentioned as the translator.