From MemberWiki

Notes:

• This wiki page holds a portion of the latest internal editorial draft for what ultimately will become the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification.

Here is the proposed way for the IDE WG to edit this specification:

• All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say Tentatively approved or Approved) represents preliminary proposed text that requires further review and discussion.
• Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
• When an item has been deemed complete by the WG chair due to committee consensus, then the annotation Approved will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
• When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation Tentatively approved will be placed at the end of given block of text (e.g., paragraph or bullet).

11 Localization

Introduction

This chapter describes the localization features within OpenAjax Metadata such that it is possible to localize the various text strings within the OpenAjx Metadata files and localize other content (such as icons) that are referenced by the metadata files.

The key localization features in OpenAjax Metadata are:

• Message bundles - Message bundles each contain the localization strings corresponding for a particular language and locale. A message bundle can be stored in a message bundle file that conforms to a particular file naming convention or can be included inline within a widget metadata file or an API metadata file.
• Variable substitution - The text or HTML content of certain elements (e.g., the <content> element) may contain localization variables, identified by percent-percent syntax (e.g., %%first_name_string%%). The localization variables will be replaced by the string found within the message bundle file that corresponds to the user's current language and locale
• Element content substitution - 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 the string found within the message bundle file that corresponds to the user's current language and locale
• File substitution - There is also a feature that allows any of the referenced files to be replaced by a localized version of the file, such as when icon files are localized

The sections below provide details on these features.

Message bundles

2008-07-01 Draft Consensus: We will adopt Google Gadget's message bundle format.

2008-07-22 Draft Consensus: We will adopt Google Gadget's file naming conventions for localization files.

messagebundle_element = element messagebundle {
  messagebundle_content  &  messagebundle_attributes  &  foreign_nodes
}
messagebundle_content = (
  msg_element*
)
messagebundle_attributes = (
  lang?
)

msg_element = element msg {
  msg_content  &  msg_attributes  &  foreign_nodes
}
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 language and locale.

Message bundles can be standalone XML files that conform to a particular file naming convention or can be included inline within a widget metadata file or an API metadata file.

The following is an example of a message bundle:

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

By convention, message bundle files are named <language>_<country>.xml. Where there is no language- or country-specific value, the convention is to use ALL. For example, the file de_ALL.xml applies to all German speakers, regardless of their country. The message bundle ALL_ALL.xml is the file that is used by default.

This section needs more work. A key question to the group is whether to adopt the <Locale> element from Google Gadgets.

Variable substitution

2008-07-01 Draft Consensus: Previously, we decided it was %%whatever%% and that for escaping sometimes character entities will do the trip. Today we decided that if the lookup of the key found nothing, just leave the original %%whatever%% there for the user to see.

Not yet written

Element content substitution (the locid attribute)

2008-07-01 Draft Consensus: Approved 'locid'.

Not yet written, but it indicates that the whole content of the given element would be replaced by the result from looking up the key in the message bundle files.

File substitution

2008-05-01 Draft Consensus: We decided to pursue an approach like what Marcos has proposed to W3C, where there is a particular location in the folder hierarchy where localization files are located. There is a folder for each locale. Within each locale folder, there is (potentially) a replica of the original distribution, with locale-specific replacement files. 2008-07-22 Draft Consensus: We don't need file naming flexibility for the locale-specific replacement files: we can dictate a particular hard-coded location. 2008-07-22: But what is the hard-coded location? Could adopt the W3C approach.

Do we have a need for parameter substitution, such as "Page {0} of {1}", where some of the localized message is passed as a parameter? This is really comon in localization systems, but not sure we need it. (Jon thinks maybe what we need is to say that localization expansion happens first, and then property expansion. That way the localization string could contain things like __pagenumber__.) 2008-07-22 Draft Consensus: We don't think we need this. We are just localizing our own metadata, which has a simpler set of requirements.

Do we need flexibility with regard to localization file naming? (Jon thinks we don't need it.) 2008-07-22 Draft Consensus: We don't think we need flexibility with localization file naming. In fact, we resolved that we should just adopt the file naming approach used by Google Gadgets.

Do we need to say that all of the metadata XML files and localization files must use UTF-8 encoding? (Jon thinks that we don't need to say this. The XML files will indicate their encoding.) 2008-07-22 Draft Consensus: We concluded that this isn't a worry. XML takes care of these things for us.

Editor: Need to make sure the spec is updated per the above resolutions, then remove the above colored comments.