Internationalizing Messages in Jelly Views

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Introduction

Jenkins supports internationalizing messages in Jelly views.

In Jenkins, you add a .properties file with the .jelly file in the same directory. Any changes of .properties do not require a restart of Jenkins.

Properties Example

As an example, consider the following jelly page:

src/main/resources/org/example/package/index.jelly:

<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:s="/lib/form">
<div>${%message}</div>
</j:jelly>

Then you could add, for example, a Chinese localization file simply as:

src/main/resources/org/example/package/index_zh_CN.properties

message=\u6D88\u606F

Properties files should be UTF-8 encoded, at least for core or plugins which already use Java 11 or newer and a core version greater than 2.358. More details can be found in JENKINS-41729. For older plugins, all non-ASCII characters need to be converted into hexcode. Modern IDEs do it automatically, so you can be just writing localizations in the target languages there.

Helpfile Extension

In some objects a help section can be defined, which loads html files. Consider this small example:

src/main/resources/org/example/package/index.jelly:

<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:s="/lib/form">
<s:optionalBlock title="${%message}"
                        help="/plugin/PLUGIN_NAME/help-message.html"
                        checked="${it.config.message}"
                        name="message-name" />
</j:jelly>

The help-message.html file and localized versions, such as help-message_de.html for the german version, should be placed in the webapp folder, so that these get copied over to the plugin directory. Jenkins will take care of loading the correct html to the corresponding language.

References