Internationalising your gadget

This page gives an overview of the standard gadget API for internationalisation, and details of the features provided specifically by the Atlassian Gadgets framework.

Overview of the Google Gadgets API for Internationalisation and Localisation

Atlassian gadgets support internationalisation and localisation as defined in the Google gadgets API.

Message Bundles

Any text that is visible to users, and therefore needs translating, will live in external XML files called message bundles. You will have one message bundle for the original language, plus a number of additional message bundles for the other supported languages.

Message bundles are XML files with a top element of <messagebundle>. Each message bundle contains the translated strings for a given locale. Each string is identified by a unique name that is the same across all your message bundles.

Message bundles can be hosted at any URL and can be shared between applications.

Using the Message Bundles in your Gadget

In your gadget XML specification you will have a list of <Locale> elements that specify the message bundles used by your gadget. The <Locale> tag lives in the <ModulePrefs> section of the gadget XML specification and links the language to the relevant message bundle.

Please refer to the Google documentation for more details.

Additional Features Provided by Atlassian Gadgets

The Atlassian Gadgets framework allows you to specify #-directives in your gadget specification XML file that will be replaced by generated content at run time. These #-directives are provided by the Atlassian Gadget Publisher plugin. They work for any gadget that is provided as a plugin in an Atlassian application. The #-directives do not work for gadgets that are served from an external web server.

#-directives are sometimes also called 'macros' or 'pseudo-macros'.

You can use the \#-directive described below with any Atlassian application that supports language packs

Alternatively, you can choose to create your own message bundles and code your own <Locale> elements instead of using the #-directive described below.

`#supportedLocales` Directive

The Atlassian Gadgets framework scans your gadget specification XML file. If it encounters a #supportedLocales directive, it will:

Retrieve the language and country information for all of the installed language packs.
Replace the #supportedLocales directive with a <Locale> element for each combination of language and country, as required in the gadget XML specification.

The messages attribute of each <Locale> element will point to a location in the application that publishes the gadget. This location provides a dynamically-generated message bundle created by finding all of the internationalisation property keys that begin with one of the prefixes specified in the #supportedLocales directive.

Parent Element: <ModulePrefs>

Format: #supportedLocales("mygadget.prefix") where mygadget.prefix is a prefix common to the message keys defined in your plugin's internationalisation file. It is possible to specify multiple prefixes by separating them with commas, for example #supportedLocales("gadget.common,gadget.introduction").

Example: Here is a snippet of the gadget XML using the #supportedLocales directive:

1
2
<ModulePrefs
    title="__MSG_gadget.introduction.title__" 
    directory_title="__MSG_gadget.introduction.title__" 
    description="__MSG_gadget.introduction.description__">
  <Require feature="dynamic-height"/>
  <Require feature="settitle"/>

  #supportedLocales("gadget.introduction")
</ModulePrefs>

At run time, the above section of the gadget XML will be replaced with the following:

1
2
<ModulePrefs
    title="__MSG_gadget.introduction.title__" 
    directory_title="__MSG_gadget.introduction.title__" 
    description="__MSG_gadget.introduction.description__">
  <Require feature="dynamic-height"/>
  <Require feature="settitle"/>

  <Locale messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/ALL_ALL.xml"/>
  <Locale lang="fr" country="FR" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/fr_FR.xml"/>
  <Locale lang="de" country="DE" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/de_DE.xml"/>
  <Locale lang="pt" country="BR" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/pt_BR.xml"/>
  <Locale lang="it" country="IT" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/it_IT.xml"/>
  <Locale lang="de" country="CH" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/de_CH.xml"/>
  <Locale lang="en" country="US" messages="http://myhost.com:port/myapp/rest/gadgets/1.0/msg/gadget.introduction/en_US.xml"/>
</ModulePrefs>

Creating your Gadget XML Specification
Writing an Atlassian Gadget
Gadget Developer Documentation