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:
- Create a new module
- Adjusting of the basic folder structure
- Creating the locale file
- Testing the new locale
- Exporting the module
- Please contribute
Create a new module
To translate the workplace, you have to create a new module. This is done as follows:
- Go to the "Administration" view in OpenCms.
- Make sure you are in an "Offline" project.
- Click on the icon "Module management". You will see a list of all installed modules.
- 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:
- Administration point:
NOT checked (default)
- View: NOT
- Export classes/folder:
- 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)
- 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.
- Left-Click on the icon left to the new module package name.
- 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.
- Now you see the "Module Dependencies" dialog.
Leave that as it is and just press "Continue >>".
Your localization module should not require a dependency.
- Now you see the "Module properties" dialog.
Press "New" to create a new module parameter.
The dialog must be filled our as follows:
additionalresources (mind the correct spelling!)
- Type: string
/system/workplace/locales/it/ (replace "/it" with the 2 letter ISO code of your language)
be left empty]
- 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
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
- Select the view "Explorer" in the head of the OpenCms workplace.
The current VFS tree of your OpenCms installation is shown.
- You should now see a folder named like your newly created module
org.opencms.locales.it in this example). Open this folder.
- In the module folder you find the following subdirectories:
You only need the
classes folder for a localization module.
Delete all other folders in the module.
classes folder will have a subdirectory structure
org/opencms/locales/it/ (in this example). Change
the subdirectory structure to be
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.
- Now switch to the folder
Create a folder with the 2-letter iso code for your new locale
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
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:
So in our Italian example, the file name is
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:
We recommend using the tool as this is much easier.
Some examples of how entries in the properties file look like:
login.message1=This is a password protected area.
login.message2=Please enter your user name and password.
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
Your properties file must
as well contain the following three entries, which are explained below:
version=$Revision: 1.3 $
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
A list of supported
content-encoding entries looks like this:
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
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
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
Confirm with "Ok" after the export is finished.
Now your module should have been written to
in our example with the filename
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.
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 firstname.lastname@example.org.
We will make it available for download on the OpenCms website.
You (or your company) will of course be mentioned as the translator.