OpenCms Documentation

The bundle editor

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 10.5 Documented since: 10.5 Latest revision for: 10.5.1 Valid for OpenCms: 13.0

Since version 10.5, OpenCms ships with an additional editor for message bundles. It can be used for property and XML resource bundles and makes editing easier since:

  • Each key used in at least one language is shown for each translation
  • Errors are shown when you try to add already existing keys
  • Keys and messages can be sorted and filtered in the editor

Moreover the editor supports bundle descriptors that allow to fix the key set and provide additional information for the keys.


How to open the bundle editor

The bundle editor opens, when you open a resource of type

  • XML resource bundle (xmlvfsbundle)
  • Property resource bundle (propertyvfsbundle)
  • Bundle descriptor (bundledescriptor)

by clicking it in the explorer or choosing Edit in the resource's context menu.

We recommend using property resource bundles instead of XML resource bundles. XML bundles lost there benefit with the bundle editor and are deprecated by now.

How to use the bundle editor

The bundle editor shows the messages of a bundle for one translation. If you do not use a bundle descriptor, it always shows every key that is used in at least one translation. Here's how the editor looks like for a bundle without descriptor.

Fig. [bundle_editor]: Editing a bundle that has no descriptor

The editor has default editor options Publish, Save, Save & Exit and Exit in the toolbar. Additionally, it provides the following options.

Language switch

Switch the language to the one you want to add translations for. You can switch between all locales available for the bundle resource you edit. If you switch to a language, for which no translation exists yet, the respective node in the xmlvfsbundle or the respective propertyvfsbundle file is added automatically.

If you open a propertyvfsbundle that contains a translation to a locale that is not available, the editor shows a warning and switches to another, available, locale. I.e., you can't edit the translation with the editor.


You can sort by each column (ascending or descending) by clicking on the columns header.


You can filter the message entries by using the filter fields directly below the table's header. Filters are only applied to the respective column they are added to.

Add key

Keys are added by the "Add key" input field. Type the key, press Enter or click the plus icon to add the key. If the key already exists, an error is displayed and the key is not added.

Remove entry

Click the minus icon at the very right of a row to remove the entry. The entry is removed for all translations. If you want to remove only the current translation, remove the content of the "Translation" field and leave this field empty.

Add bundle descriptor

The toolbar has an option for adding a bundle descriptor. The descriptor is placed in the folder the currently edited bundle file is placed in.

If you translate the value of one key, you can copy the translation to another language first. A right-click on the empty translation field will show the context menu as displayed in figure [bundle_editor_copy_from].

Fig. [bundle_editor_copy_from]: Paste the translation to another language in the empty "Translation" field.

Editing bundles with descriptors

Read more about bundle descriptors here.

When a bundle descriptor is added, the editor shows and stores only keys specified in the descriptor. Additionally to the options that are available for bundles without a descriptor, the editor has two extra options:

View switch

If you have write access to the bundle descriptor, you can switch between "Adjust bundle" and "Translate" mode. In the "Adjust bundle" mode you can edit all information. In particular, you can add new keys or remove entries. In the "Translate" mode, you can only edit translations. The key set and all other information stored in the bundle descriptor is not editable.

The editor opens in "Translate" mode.

Adjust visible columns

You can show or hide the columns of the extra information stored in the bundle editor (by default "Description" and "Default Value". When you open the editor for a bundle with descriptor only the non-empty of these columns are shown initially.

Below, you see how the editor looks like in the different views when editing a bundle with descriptor.

In the translate view no keys can be added or removed, only the translation is editable.
The visible colums can be adjusted as in the "Adjust bundle" view. Initially all non-empty columns are shown.

Fig. [translate_view]: The "Translate" view when editing a bundle with descriptor

In the "Adjust bundle" view you edit the descriptor and the bundle at the same time. Hence, you can edited all information.

The view is only available if you have write access on the bundle descriptor.

Fig. [adjust_bundle_view]: The "Adjust bundle" view when editing a bundle with descriptor

Configuration of the bundle editor

When using a bundle descriptor, the column headings of the bundle editor can be adjusted. The bundle descriptor essencially adds up to two pieces of (unilingual) extra information for each key. By default these are "Description" and "Default Value". But you may want to provide different information instead. To do so, simply rename the "Description" and "Default Value" column headers in the bundle editor.

Add an extra message bundle containing the adjusted names of the column headers and set the bundle's base name as value for the property bundle.descriptor.messages at the bundle descriptor. The extra bundle should contain the following keys, or at least the one's for which you want to overwrite the default messages:


Renaming may for example be interesting, if you use bundles to store technical values. If these are numbers, you could provide a lower and an upper bound via the extra information in the bundle descriptor.

Additional features of the bundle editor

Lazy locking

Since OpenCms 10.5.1, the bundle editor locks the opened files lazily. A lock is placed only when you really start editing data stored in the specific file. Whenever an input field in the editor's table loses it's focus, it is checked if the value has changed. You will be warned, when changes are not possible because locking failed. In this case the original value contained in the input field will be restored.

Lazy locking allows you in particular to translate to different languages in parallel when using property resource bundles.

Key modification behavior

When you change or delete a key, the key will be changed or deleted in all translations (and the bundle descriptor) if it is present.

Note that the operation requires write access to all localizations where the key exists, i.e., it might not be possible due to locking problems. In this case you will get a warning.

Behavior on save

When you edit property bundles, the property content-encoding is set at the file on save. This prevents encoding problems when you export your bundle from one system and import it to another system with different default encoding.

When a bundle uses a descriptor and a bundle file contained messages with keys not declared in the descriptor, these are removed on save.

Note that this remove operation happens only for translations you actually edited, other translations are simply not rewritten.

Behavior on publish

When you use the "Publish" option in the editors toolbar, your current changes are saved and the publish dialog appears in "Direct publish" mode. The resources shown are all (changed) resources that form the bundle, i.e., all property bundle files and the bundle descriptor.

Unlike other editors, the bundle editor does not close when the publish action is triggered. Thus, you can directly go on and edit - with one tiny exception:

You can only proceed to edit the bundle when the publishing finished for the resources you want to edit. Otherwise they are locked with a publish lock. So you might have to wait a moment until you can proceed to edit the bundle.

Converting XML bundles to property bundles

When you open an XML bundle in the editor, the toolbar has an extra button "Convert to property resource bundle" as shown in the figure below. Pressing the button will:

  • Add for each locale in the XML bundle a separate property bundle file named {bundle base name}_{locale} in the folder where the XML bundle file is located
  • Delete the original XML bundle file
Nothing will be published.
Fig. [convert_bundle]: Option to convert an XML bundle to a property bundle

Restrictions of the bundle editor

The editor assumes that all resources of a bundle, except the descriptor, are placed in the same folder. That is, for the bundle my.bundle which is stored as property resource bundle, all localizations, i.e., the resources my.bundle_en, my.bundle_de, etc. must be placed in one folder. Only the descriptor my.bundle_desc can be placed somewhere else.

The editor handles only XML resource bundles, property resource bundles and bundle descriptors. It can't be used to edit default Java property files.