Zimlet Developers Guide:Internationalization

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Zimlet Developers Guide: Internationalization

   KB 3275        Last updated on 2021-07-17  

(0 votes)
Warning: You are looking at legacy Zimlet documentation. For Zimbra Modern UI Zimlet development go to: https://wiki.zimbra.com/wiki/DevelopersGuide#Zimlet_Development_Guide.
Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png Developing Zimlets Zdg-6-menu-icon-advanced.jpg
Advanced Concepts
Application Context
Java & JSP
Zimlet Tab
Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets


Internationalization is the process of designing a zimlet so that it can be adapted to various languages and regions without code changes. Sometimes the term internationalization is abbreviated as i18n (because there are 18 letters between the first "i" and the last "n").

To internationalize your zimlets, you can include .properties files with your zimlet. These files will include the internationalized text resources used in your zimlet. You can include multiple properties files with your zimlet to support multiple locales.

An example zimlet is provided here.

Note: A locale is the combination of a language code and a country code. For example, the locale for the English language in the country of US is en_US. Or the locale for the English language in the country of United Kingdom is en_GB. A list of locale country codes are available at http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm

Properties File Naming Convention

The properties file must start with your zimlet name, followed by the locale and the .properties extension. These files must be in the base directory of your zimlet. The default locale for a zimlet is en_US ("English-US"). The base zimlet properties file is assumed to be English-US and does not include a locale in the file name.

For example, a zimlet named "com_zimbra_helloworld" would have the following properties files to handle English in multiple countries:

File Locale Language Locale Country Description
com_zimbra_helloworld.properties English ("en") United States ("US") The default properties resource bundle for the zimlet in the en_US default locale ("Language: English, Country: US")
com_zimbra_helloworld_en_GB.properties English ("en") United Kingdom ("GB") The properties resource bundle for the zimlet in the en_GB locale ("Language: English, Country: United Kingdom")
com_zimbra_helloworld_en_CA.properties English ("en") Canada ("CA") The properties resource bundle for the zimlet in the en_CA locale ("Language: English, Country: Canada")

Properties File Syntax

The resource keys are stored in the properties file in the format key=value. For example, for a resource key named "helloworld":

helloworld = Hello World!

Comments can be included in the properties file by prefacing the line with "#". For example:

# this is a comment in the props file
helloworld = Hello World!

Note: key names cannot contain periods (".") or dashes ("-"). Underscore ("_") is allowed. For example, "helloworld" or "hello_world" are valid key names but "hello-world" or "hello.world" are not valid key names.

Accessing Resource Properties

The resource keys in your zimlet properties files can be accessed from the Zimlet Definition File XML using the "${msg}" syntax.

For example, accessing a key named "helloworld" from an XML element:


For example, accessing a key named "helloworld" from an XML element attribute:

<menuItem label= "${msg.helloworld}" id="MY_ITEM_ID" />

To access resource keys from your Zimlet Handler Object, use the ZmZimletBase.getMessage() JavaScript method:

var str = this.getMessage("helloworld");

To access resource keys from a Template, use the Zimlet Name and the property in your template file with the <$=$> syntax:

<table cellspacing="2" cellpadding="0" border="0">
    <b><$= com_zimbra_myzimlet.myresourcekey $></b>

Additional Information

  • When building your zimlet using the Zimlet Development Directory, you will need to load the Zimbra Web Client in Development Mode (i.e. with the ?dev=1 parameter) in order for the zimlet resource properties to load.
  • Naming your Zimlet Handler Object the same as your Zimlet Name will cause sporadic results. Be sure to name the Handler Object something different than your zimlet name. For example, the Handler Object for a zimlet named "com_zimbra_helloworld" should be "com_zimbra_helloworldHandlerObject". See Zimlet Handler Object for more information.
  • See Simple Internationalization Example for a working i18n zimlet example.

Verified Against: Zimbra Collaboration Server 7.0 Date Created: 12/22/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Internationalization Date Modified: 2021-07-17

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search