Translation of the Online Help

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

Help modules

The Online Help - accessible via the help button in the top button bar - is provided with the modules org.opencms.workplace.help and org.opencms.workplace.help.[language] for each language.

The english help module org.opencms.workplace.help.en can be used as a master for your new online help.

Adjusting the basic folder structure

The help files are located in the folder

/system/workplace/locales/[your locale]/help

You can copy the english help pages as a template for your localized help.

At the new locale folder below /system/workplace/locales, you must set the value of the "locale" property to the appropriate 2-character ISO-code, i.e. "it" for italian language. Additionally, the locale must be defined in the <internationalization> section in the opencms-system.xml configuration file.

Editing the english master help pages

You can navigate through the copied help pages in the Explorer view of OpenCms and edit them either with the WYSIWYG editor or the Sourcecode editor of OpenCms just like any page.

DO NOT simply replace the english content with your translation, but create a new page element for the italian language and enter your translation there. The english page element can be deleted afterwards.

Note: You can view your contents in the editor, only. When displaying the page by clicking to the page name, the old content is still displayed or you get an error for new  pages. In order to have the new page available, you must publish the help pages and also delete the contents of the static export folder for help pages in {$TOMCAT_HOME}/opencms/export/system/modules/org.opencms.workplace.help/jsptemplates.

Adding new help pages

When creating new help pages, you have to change the path to the help master template manually,  since this template is not stored in a module "templates" folder and does not show up in the template pulldown of the "Create new page" dialog.

To do that, select another template and the "Default body" in the "Create new page" dialog. Check the "Edit properties" option, or open the properties dialog afterwards. In the advanced property dialog, enter the path to the help master template:
/system/modules/org.opencms.workplace.help/jsptemplates/help

When editing that page, normally the page element for your language should be created and displayed automatically, so you can enter you contents immediately.

Please mind to add the new pages to the navigation, your chosen page title will be displayed as navigation text.

Note: Again, you can view your contents in the editor, only. When displaying the page by clicking to the page name, the old content is still displayed or you get an error for new  pages. In order to have the new page available, you must publish the help pages and also delete the contents of the static export folder for help pages in {$TOMCAT_HOME}/opencms/export/system/modules/org.opencms.workplace.help/jsptemplates.

Changing the help page mapping

In order to have the help button in a context linked to a specific help page (i.e. opening the help in the editor opens the editor help page), you can add a properties file defining the mapping from the current workplace path to a help page. This properties file has the name " mappings_[your locale].properties" and must be stored in the classes folder of the org.opencms.workplace.help module, i.e below /system/modules/org.opencms.workplace.help/classes/org/opencms/workplace/help/.

For creating the mapping, copy the english orginal mappings.properties to mappings_it.properties and change the paths to the pages to their respective values. This step is neccessary only, if you need to have other paths and names for the help pages than the default paths/names.

Create a new help module

Switch to the adminstration view and create a new module. Fill out the dialog as follows (this example is for the Italian "it" locale):

• Package name: org.opencms.workplace.help.it (".it" for the Italian locale in this example)
• Module name: OpenCms workplace online help - {Language name} version
• Description: This module installs the {Language name} version of the online help.
• Version: 0.1 (default)
• Module group:  OpenCms Online Help
• Action class: [leave this empty] (default)
• Author name: [insert your name or company name here]
• Author email: [insert your email address here]

Don't create any module folder [leave all entries unchecked].

As module resources, add your new help folder /system/workplace/locales/[your locale]/help and potentially add the mapping properties for your locale, i.e. /system/modules/org.opencms.workplace.help/classes/org/opencms/workplace/help/mappings_it.properties for the italian example.

You have now created the new module which should be displayed in the modules overview page. 

Exporting the module

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

Click on the export button left to your module name and confirm with "Ok". Your module should now be exported. You might check if the files and the subfolders of /system/workplace/locales/it/help (for the Italian help) are listed as exported in the output.

Confirm with "Ok" after the export is finished.

Now your module has been written to {$TOMCAT_HOME}/opencms/WEB-INF/packages/modules, in our example with the filename org.opencms.help.it_0.1.zip.

You can now import that module to other OpenCms servers by switching to the "Administration" -> "Module management" view in the OpenCms workplace on another server and selecting the "Import Module with HTTP" action on top of the screen.

Note: You always have to upload the base module org.opencms.workplace.help for your localized online help to work.

Please contribute

Of course, it would be great if you contribute your online help 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.