From MemberWiki

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.

Chapter 11: Localization

Introduction

This chapter describes the features within OpenAjax Metadata that allow for localizing the various text strings within OpenAjax Metadata files.

The key localization features in OpenAjax Metadata are:

• Message bundle files - Message bundle files contain localization strings corresponding to a particular locale.
• Localization substitution for an entire string - Some elements, such as the <description> element, offer a locid attribute (e.g., locid="item_description"), which will cause the complete contents of the given element to be replaced by a string in the message bundle file that corresponds to the user's current locale.
• Localization substitution within a string - The text or HTML content of certain elements (e.g., the <content> element) may contain localization variables, identified by hash-hash syntax (e.g., ##first_name_string##). The localization variables will be replaced by strings in the message bundle file that corresponds to the user's current locale.
• BIDI support - The 'language_direction' attribute in combination with the __BIDI_* substitution strings provide convenience features that help the widget developer create widgets that display localized content that honors the dominant writing direction (left-to-right or right-to-left) associated with a particular language.
• 'lang' attribute - The 'lang' attribute, available on all elements that might contain localizable string content, identifies the natural or formal language for the content within a particular element.

The sections below provide details on these features.

Message bundle files

Message bundle files contain localization strings corresponding to a particular locale. The root element of a message bundle file MUST be <messagebundle>. Unlike the rest of OpenAjax Metadata, message bundle files are not namespaced (i.e., xmlns="").

Each given message bundle file MUST contain all of the localization strings that might apply to a given locale.

The <messagebundle> and <msg> elements

messagebundle_element = element messagebundle {
  messagebundle_content  &  messagebundle_attributes
}
messagebundle_content = (
  msg_element*
)
messagebundle_attributes = (
  empty
)

A <messagebundle> element contains any number of <msg> elements. Each <msg> element specifies a localized version of a string:

msg_element = element msg {
  msg_content  &  msg_attributes
}
msg_content = (
  text
)
msg_attributes = (
  name
)

Message bundles begin with a <messagebundle> element. Each message bundle contains any number of <msg> elements that provide the localization strings corresponding to a particular locale. The following is an example of a message bundle:

<messagebundle>
  <msg name="color">Color</msg> 
  <msg name="red">Red</msg> 
</messagebundle>

The name attribute MUST be globally unique within the given message bundle file.

(Note: the <messagebundle> and <msg> elements come from the OpenSocial Gadgets specification version 0.9.)

The <locale> element

The <locale> element (a subelement of the <widget> and <api> elements) provides the URI for a particular message bundle file.

Schema

locale_element = element locale {
  locale_content  &  locale_attributes  &  foreign_attributes
}
locale_content = (
  empty
)
locale_attributes = (
  lang?  &  language_direction?  &  messages
)

Child content

The <locale> MUST be an empty element (i.e., no child content).

Attribute summary

Attribute details

'lang' attribute

The lang attribute identifies the natural or formal language for the messages included within the given message bundle file. The values of the attribute are language identifiers as defined by IETF BCP 47.

'language_direction'attribute

The lang attribute specifies the dominant writing direction for the language(s) used within the given message bundle file. The value can be either ltr or rtl.

'messages' attribute

The messages attribute holds the URI for the message bundle file. If the lang attribute is specified, then the messages refers to the message bundle file corresponding to the value of the lang attribute. If the lang attribute is not specified, then the messages attribute refers to the default message bundle file.

Example

<widget xmlns="http://openajax.org/metadata" id="http://example.com/MyWidget" name="MyWidget">
  <locale messages="http://example.com/locales/ALL_ALL.xml"/> 
  <locale lang="fr" messages="http://example.com/locales/fr_ALL.xml"/>     
  <locale lang="fr-CA" messages="http://example.com/locales/fr_CA.xml"/>
</widget>

In the above example:

• If the user's locale is "fr-CA", then the appropriate localization file is fr_CA.xml.
• If the user's language is "fr" (or any variation of French other than "fr-CA"), then the appropriate localization file is fr_ALL.xml.
• Otherwise, the appropriate localization file is ALL_ALL.xml.

RFC 4647 provides algorithms that developer tools can use for matching language tags defined by the 'lang' attribute with the user's current locale.

(Note: the <locale> element comes from the OpenSocial Gadgets specification version 0.9, but instead of uppercase <Locale> in OpenSocial, the element is lowercase for consistency with the other elements in this specification.)

Localization substitution for an entire string

The 'locid' attribute provides a mechanism by which an entire string value defined within the metadata file can be entirely replaced with a localized version of the given string.

'locid' attribute

The 'locid' attribute is available on all elements that might contain localizable string content.

The presence of a locid attribute within a metadata file tells the developer tool that localized versions of the given text content may exist. The value of the locid attribute provides the lookup key into the message bundle files.

For example, suppose there is a <description> element in the metadata file as follows:

<description locid="hello_world">Hello world</description>

And suppose the current locale is "fr-FR" and that there is a <messagebundle> element as follows:

<messagebundle>
  <msg name="hello_world">Bonjour tout le monde</msg>
</messagebundle>

Because the current locale is "fr-FR" and there is a localized version of the string with locid of "hello_world" that matches the "fr-FR" locale, the developer tool MUST display the localized string "Bonjour tout le monde" instead of the original string "Hello world".

Localization substitution within a string

As described above, the 'locid' attribute allows for an entire string to be replaced by a localized version of that string. This specification also provides a mechanism for localization of selected content within a string via the ##name## localization variable substitution feature. For detailed information on this feature, see Localization value substitution in the Variable Substitution chapter.

BIDI support

The specification defines convenience features that help the widget developer create widgets that display localized content that honors the dominant writing direction (left-to-right or right-to-left) associated with a particular language.

The two key features related to BIDI support:

• The 'language_direction' attribute on the <locale> element allows the widget metadata to indicate the dominant writing direction for the language(s) used within the given message bundle file.
• __BIDI_* substitution variables, which allow a widget developer to define appropriate __BIDI_* substitution variables within the widget's presentation markup to ensure that the content will display using a language-dependent writing direction (i.e., left-to-right or right-to-left). For detailed information on this feature, see BIDI direction substitution in the Variable Substitution chapter.

'lang' attribute

The 'lang' attribute is available on all elements that might contain localizable string content.

The lang attribute identifies the natural or formal language for the content within a particular element. The values of the attribute are language identifiers as defined by IETF BCP 47. The attribute does not have a default value.