Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.2

This topic is concerned about the user interface localization for OpenCms users. The locale of these interfaces we call workplace locale. The topic tells you:

  • How to localize the content editors
  • How the localization of the traditional workplace and the ADE interfaces works

To understand the topic fully, you have to know how message bundles work in OpenCms.

The difference between a multilingual website and the multilingual OpenCms GUI

Localization has two facets: Multilingual websites and multilingual user interfaces. If, for example, you have a content editor that is natively English and thus prefers the English language. He may want to have all menus, infos, and so on, coming from OpenCms in English. However, if he edits a German website, the content he sees and modifies has to be German. The difference is noticed best by Figure [two_languages_content_editor].

The editor dialogs are all shown localized in English, which is set as user preference and called workplace locale. The language of the content, or more specific the language version that is edited, is German, as you see in the "Language" switcher at the top of the editor. The locale of the content, we usually refer to as locale.
Fig. [two_languages_content_editor]: The different localizations: GUI and content language

Configuring the available workplace locales

The workplace locale is set per user and can be chosen via his preferences, either via the traditional workplace's "Preferences" option, or the "Preferences" option in context menu of the ADE toolbar in the page or sitemap editor. The locales you can choose are determined by the presence of special folders: If a folder /system/workplace/locales/{locale} exists, the according language can be chosen. Thus, to add a new locale, or to delete a locale it suffices to just add or remove such a folder. In a default installation, the folders shown in Figure [available_workplace_locales] are present.

If a folder with the locale's name is present, the according language can be set in the user preferences. If the messages are really localized accordingly depends on the message bundles located in the locale's folder. If keys are missing, English is chosen as default.

In a default installation, the locales shown in the figure are present.

Fig. [available_workplace_locales]: The available workplace locales

Of course, adding a single folder is not sufficient to have a new locale. In the new folder, all message bundles (Java property files) necessary for the GUI localization must be present. If whole bundles or keys are missing, English is used as default. To see how these messages are structured, browse the subtree for de. In particular the messages subfolder is interesting. The structure is based on the different modules.

English message bundles are directly shipped within the workplace modules libraries (jar files), so you will not find the messages subfolder under en.

To put the message bundles you may add in your locale usable, you have to export your locale folder, say pt for Portugese, to {webapp home}/WEB-INF/classes. Therefor, put your localization in a module and set the export point via the module configuration. Here's an old (but still mostly valid) tutorial on how to add the localizations (the wizard mentiond there is not available anymore).

Localization for resource types

For each resource type in OpenCms, you basically need three different localized values:

  • Title (shown in workplace and ADE add wizard)
  • Description (shown in workplace and ADE add wizard)
  • Title for the "New" dialog of the traditional workplace shown when adding a new content of the type

The keys for these values have to be placed in workplace message bundlesBundles ending with .workplace and property files name messages are treated special in OpenCms. They are called worplace message bundles. and conform to the following name scheme:

Resource type specific message keys
fileicon.{resource type name}

The key is used as title of the resource type in the ADE "Add wizard" of the page editor and the "New" wizard from the workplace.{resource type name}

The key is used as title of the dialog that appears when creating a new resource of the type via the "New" wizard from the workplace.

desc.{resource type name}

The key is used as description of the resource type in the ADE "Add wizard" of the page editor and the "New" wizard from the workplace.

If you add a new resource type to OpenCms, using the "Add resource type" wizard in the "Module Management" in the administration view, the wizard does already all the configuration for the type in the opencms-modules.xml and adds the message keys just discussed to a suitable message bundle. This bundle is located under the i18n/ subfolder of the module folder and named {module name}.workplace. The keys are entered for the current workplace locale. So you just need to add keys for the other locales.Note that via the content editor you can only edit the locales configure (for website contents) which are not necessarily identical to the workplace locales. Localization as done by the wizard is the preferred way for localizing resource types.

Note that, to make the keys work, their use must be configured correctly in the opencms-modules.xml. This is automatically done by the wizard as long as you do not leave the dialog fields empty where title etc. must be added.

Content specific localization of the content editor

The appearence of the content editor of OpenCms relies heavily on the structure of your content. In particular, the form based editor shows all the schema elements of your content as an editor field. Such a field has a label and optionally a tooltip. Furthermore, the editor can have tabs, whose lables can also be localized.

The keys for such localization have to follow a special name scheme.

Localizing the content editor: Naming schemes for the message keys
label.{schema type name}.{schema element name}

The key for localizing the name of the schema element as shown in the content editor.

label.{schema type name}.{schema element name}.help

The key for adding a localized tooltip, shown when hovering over the schema element's name as shown in the content editor.

label.{schema type name}.{tab's name attribute}

The key for localizing the name shown in a tab.

The keys can either be added to the {module name}.workplace resource bundle that's included in the module where the resource type is defined in, or they can reside in a separate bundle, usually called {module name}.{resource type name}, also located in the module's i18n/ subfolder. The second option is the preferred one, but it requires you to make the message bundle explicitly available in the schema of the content (the XSD) by adding the following subnode to <xsd:annotation>/<xsd:appinfo>:

    <resourcebundle name="{name of the bundle}"/>
    <!-- more different nodes -->

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.