<< Back - Alkacon logo

OpenCms 6.0 interactive documentation:

How to translate the OpenCms Online Help

OpenCms logo - Forward >>

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:

  1. Upload help modules
  2. Create a new help module
  3. Adjusting of the basic folder structure
  4. Editing the english master help pages
  5. Adding new help pages
  6. Exporting the module
  7. Please contribute
Upload help modules

For the Online Help, you need the base module org.opencms.help and the English Online Help module org.opencms.help.en which serves as a master for your new Online Help. You can download these modules at the OpenCms website http://www.opencms.org. Now you have to upload those modules in the Backoffice of OpenCms:

  1. Go to the "Administration" view in OpenCms.
  2. Make sure you are in the "Online" project.
  3. Click on the icon "Module management". You will see a list of all installed modules.
  4. Click on the icon "Upload module from" on the upper left of the screen. The "Upload module from" dialog opens.
  5. Choose "local computer" and then search for the modules zip file in the filesystem.
  6. Upload both help modules in this manner.
Create a new help module

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

  • Package name: org.opencms.help.it (".it" for the Italian locale in this example)
  • Version: 1 (start with 1 and increase for new versions)
  • Module name: OpenCms workplace online help - {Language name} version
  • Description: This module installs the {Language name} version of the online help.
  • Simple module typ: checked (default)
  • Administration point: NOT checked (default)
  • View: NOT checked (default)
  • Export classes/folder: NOT checked
  • 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 modules overview page. Next step is to add a property to the new 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 date, you can do so here later. Press the "Continue >>" button.
  3. Now you see the "Module Dependencies" dialog. Leave that as it is and just press "Continue >>". Your localization module does 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/help/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.

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 the newly created module i.e. org.opencms.help.it in this example. Open this folder.
  3. In the module folder you find the following subdirectories: classes, default_bodies, elements, lib and templates. Delete all folders in the module.
  4. Now switch to the folder /system/workplace/help/. Lock the subfolder en/. Use the folders context menu to copy the folder. Enter a folder /system/workplace/help/it (where it stands for the Italian example) as destination of the "copy to..." field. The entire contents of the english Online Help are now copied to this new subfolder.

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. Replace the english content with your translation.

Adding new help pages

To create new help pages you have to change the visibility of the master template which is needed for the Online Help pages.

To do that, switch to the folder /system/modules/org.opencms.help/templates/ and change the permissions of the file help_default to rwvrwvr-v- (i.e. just add the "v" flags). Now you should see the template "Online help default template" in the "New page" dialog of OpenCms. Select this template to create new help pages in the subfolders of /system/workplace/help/it/, where it is an example for the Italian locale.

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

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 icon left to your module name and select "Export" and confirm with "Ok". Your module should now be exported. You might check if the files and the subfolders of /system/workplace/help/it (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/export/modules, in our example with the filename org.opencms.help.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.

Note: You always have to upload the base module org.opencms.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.

©2003-2005 Alkacon Software (http://www.alkacon.com) - The OpenCms experts