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:

1. Create a new module
2. Adjusting of the basic folder structure
3. Creating the locale file
4. Testing the new locale
5. Exporting the module
6. Please contribute

Create a new module

To translate the workplace, you have to create a new module. This is done as follows:

1. Go to the "Administration" view in OpenCms.
2. Make sure you are in an "Offline" project.
   
3. Click on the icon "Module management". You will see a list of all installed modules.
   
4. Click on the "Create module" button on the upper left of the screen. The "Create module" dialog opens. The dialog should be filled out as follows (in this example we used the "it" locale for the Italian language):
   
   
   • Package name: org.opencms.locale.it (".it" for Italian example locale, use the 2 letter ISO code for the language of your choice)
   • Version: 1 (start with 1 and increase for new versions)
   • Module name: Italian localization for the OpenCms workplace (for the Italien translation in our example)
   • Description: This module contains the Italian language localization files for the OpenCms workplace. (Description for our example)
   • Simple module typ: checked (default)
   • Administration point: NOT checked (default)
   • View: NOT checked (default)
   • Export classes/folder: checked (default)
   • Export lib/folder:NOT checked
   • 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]
   • Date created: [dd.mm.yyyy] (creation date of the module, please mind the date format)
5. Click "ok".

You have now created the new module which should be displayed in the module overview page. Next step is to add a property to the newly created module.

1. Left-Click on the icon left to the new module package name. Choose "Administrate".
   
2. First you see the "Module administration" dialog which looks in essence the same as the "Create module" dialog. In case you want to make any changes to your module data, you can do so here anytime. Press the "Continue >>" button.
3. Now you see the "Module Dependencies" dialog. Leave that as it is and just press "Continue >>". Your localization module should not require a dependency.
4. Now you see the "Module properties" dialog. Press "New" to create a new module parameter. The dialog must be filled our as follows:
   
   • Name: additionalresources (mind the correct spelling!)
   • Type: string (default)
   • Value: /system/workplace/locales/it/ (replace "/it" with the 2 letter ISO code of your language)
   • Description:[can be left empty]
5. Confirm your input with "Finish".

You should now see the "Module properties" dialog again, and it should list the new entry for "additionalresources" as you have just entered it.

Note: The "additionalresources" just tells the system to treat all resources at the given location and below as part of the module. So they are exported with the module in case you export it, which is important for the locales. Also, in case you delete the module all resources listed at "additionalresources" will be deleted without a warning, so be careful to only include only resources that really are a part of the module. You can add more than one resource by separating entries with a semicolon ";", and you can even add individual file names.

For the locales you only need one directory below /system/workplace/locales/ named with the 2- letter ISO code of the new locale. This of course has to be created - read on for more details.

You are now finished with the initial module setup. You should be in the module overview page.

Adjusting of the basic folder structure

1. Select the view "Explorer" in the head of the OpenCms workplace. The current VFS tree of your OpenCms installation is shown. Open the /system/modules/ folder.
2. You should now see a folder named like your newly created module (i.e. org.opencms.locales.it in this example). Open this folder.
3. In the module folder you find the following subdirectories: classes, default_bodies, elements and templates. You only need the classes folder for a localization module. Delete all other folders in the module.
4. The classes folder will have a subdirectory structure org/opencms/locales/it/ (in this example). Change the subdirectory structure to be  com/opencms/workplace/ by renaming and/or deleting the existing directories. The folder name com/opencms/workplace/ must be the same for all localization modules, as this is the Java package name where the localization ResourceBundles are expected.
5. Now switch to the folder /system/workplace/locales/. Create a folder with the 2-letter iso code for your new locale there, e.g. it for the Italian example. This subfolder can be left empty but is needed for the translation to work in OpenCms. Maybe you should copy the "readme.txt" from the en/ locale folder there just to have something in the folder.

Creating the locale file

Older OpenCms versions (4.x) exclusively used a proprietary localization mechanism based on XML. OpenCms 5.0 uses standard java.util.ResourceBundles for the localizations.

Switch to the module folder of your new module and there to the classes/com/opencms/workplace/ subdirectory. In this directory, you have to create a file with the following name: workplace_[locale].properties So in our Italian example, the file name is workplace_it.properties. You can create a new file by clicking the "New" Button on the top screen and then select "Text" as file type. In the following dialog, you just need to input the name as explained above, you do not need to fill out "Title", "Keywords" or "Description".

For the creation / editing process of the new property file you should use the localization tool available in this module. Click here for a short description of the tool.

Alternatively, you can get the last version of the english property file as base for the translation using the OpenCms web based CVS viewer at the URL: http://www.opencms.com/cgi-bin/cvsweb.cgi/opencms/src/com/opencms/workplace/workplace.properties. We recommend using the tool as this is much easier.

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

...
login.title=Login
login.message1=This is a password protected area.
login.message2=Please enter your user name and password.
login.username=Username
login.password=Password
login.button=Login
...

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.

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.

Your properties file must as well contain the following three entries, which are explained below:

version=$Revision: 1.3 $
name=Italiano
content-encoding=ISO-8859-1

The version key value is generated by the CVS and can be left as it is.

The value of the key name is the language name as it will appear in the User settings dialog of the OpenCms workplace.

The value of the key content-encoding is the encoding that will be used for the workplace when switching to that language. The workplace actually has no encoding of it's own but will use the encoding set in the language file. In case you don't know what to use here, "ISO-8859-1" will be o.k. for all Western European based languages.

Additionally, OpenCms supports "adaptive encoding" for a workplace localization property file. This means you can give a set of supported encodings for a language in the property file, not just a single encoding. It's a good idea to always add "UTF-8" at least as an additional option to any encoding, so that your translation can be used without problems in Unicode environments. A list of supported content-encoding entries looks like this:

content-encoding={ISO-8859-1;UTF-8}

In this case, OpenCms will try to find it's default encoding (the encoding OpenCms is configured to run with in the opencms.properties ) in the list of supported encodings. If it does, it will use this default encoding for the workplace, which is good because in this case the workplace encoding matches the preferred encoding of the user. If the default encoding is not found in the list of supported encodings, OpenCms will use the first entry in the list for that language workplace encoding (ISO-8859-1 in our example).

The "adaptive encoding" works because the localization property files are always treated interally as Unicode. This is the standard Java behaviour. Please note that becasue of this, international charsets must be treated in a special way in ResourceBundle property files. The FAQ at http://www.sun.com/developers/gadc/faq/java/java1.4.html explains all the details. Check out the "Resource Bundles" headline for more information.

Testing the new locale

Now let's say you have translated the file as described, saved the result and are ready for a test.

First, you must really make sure that all your changes are published. Provided you are working in the default "Offline" project, just press the "Publish project" button on the workplace top frame to do so.

If your changes are published, all files in the workplace should appear black in the "Offline" project.

After publishing for the first time, let's check if the properties file has 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 com/opencms/workplace and the properties file you have created should be contained in the bottom-level directory.

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.

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 properties file is 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/export/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.

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.