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:
To translate the workplace, you have to create a new module. This is done as follows:
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.
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.
/system/modules/
folder.org.opencms.locales.it
in this example). Open this folder.classes
, default_bodies
, elements
and templates
. 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 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./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.Older OpenCms versions (4.x) exclusively used a proprietary localization mechanism based on XML. OpenCms 5.0 now 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.1 $ 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.
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.
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.
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.
]]>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:
To translate the workplace, you have to create a new module. This is done as follows:
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.
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.
/system/modules/
folder.
org.opencms.locales.it
in this example). Open this folder.
classes
, default_bodies
, elements
and templates
.
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 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.
/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.
Older OpenCms versions (4.x) exclusively used a
proprietary localization mechanism based on XML. OpenCms 5.0 now 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.1 $ 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.
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.
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.
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.
]]>