Zimlet Developers Guide:Internationalization

1. Zimbra Tech Center
2. Community Sandbox
3. Zimlet Developers Guide:Internationalization

Zimlet Developers Guide: Internationalization

 - This is archive documentation, which means it is not supported or valid for recent versions of Zimbra Collaboration.

You are looking at legacy Zimlet documentation. For Zimbra Modern UI Zimlet development go to: https://wiki.zimbra.com/wiki/DevelopersGuide#Zimlet_Development_Guide.

Introduction

Getting Started

Dev Environment Setup

Developing Zimlets

Advanced Concepts Application Context Templates Java & JSP Portal Zimlet Tab Internationalization

API Specifications

Example Zimlets

Internationalization

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:

<toolTipText>${msg.helloworld}</toolTipText>

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">
  <tr>
    <td>
    <b><$= com_zimbra_myzimlet.myresourcekey $></b>
    </td>
  </tr>
</table>

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.