IDE Issue 3

From MemberWiki

Contents 1 IDE Issue 3: Widget metadata localization 1.1 Original write-up 1.2 Existing practice 1.2.1 Java 1.2.2 W3C ITS 1.2.3 Dojo 1.0 1.3 Analysis 1.4 Jon's first proposed recommendation (which did not excite people at 20080103 phone call) 1.5 Revised proposed recommendation

IDE Issue 3: Widget metadata localization

Original write-up

During recent IDE WG discussion, we were sometimes scratching our heads about which metadata fields required localization and which ones did not. Also, we need to try to anticipate the typical workflows by which Ajax toolkit vendors and IDE vendors will localize their widget metadata.

There is a question about whether the original metadata should include any text values for localizable fields (e.g., perhaps the English version is included, such as "OK" or "Cancel") or instead should only include a handle (e.g., "{LOCALIZATION_FIELD_OK_LABEL}").

Existing practice

Java

This is an incomplete write-up. It would be nice if someone could finish this section.

Java has resource bundle files. Here is a link to an article:

• http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/

The strings are contained in resource files that have the format key=stringvalue. Here is an example:

HELLO_TEXT=Hello, world!
GOODBYE_TEXT=Goodbye everyone!
CANCEL_BUTTON_TEXT=Cancel

The Java language system includes various APIs for loading resource bundles (with a precedence algorithm about bundle selection) and for loading a particular localized string from out of a bundle:

ResourceBundle res = ResourceBundle.getBundle("MyResource");
String strHello = res.getString("HELLO_TEXT");

The resource files are named by having the default resource file without language designation (e.g., "MyResource.properties") and language-specific resource files with a language designation in the file name(e.g., "MyResource_fr_CA.properties" for French/Canada and "MyResource_fr.properties" for French normal). (I am pretty sure that one of the web pages said that the resource files should be put into the same folder as the class files, but a Java expert should chime in and provide the right information.)

W3C ITS

Because we are using XML, people who are attempting to localize the metadata files have XML tools at their disposal, such as XSLT, and other relevant XML standards, such as W3C ITS (http://www.w3.org/TR/its/).

W3C ITS starts off with the default where all XML text nodes are translatable and all XML attribute nodes are not translatable. For a given XML grammar, you override those defaults via a set of ITS rules which use XPath selectors to identify those parts of the XML grammar that differ from the defaults. Here is how the ITS rules look for the W3C's XML Spec language:

<its:rules xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0">

 <!--The following rules are for xmlspec-i18n.dtd-->
 <its:termRule selector="//qterm"/>
 <its:dirRule dir="ltr" selector="//*[@dir='ltr']"/>
 <its:dirRule dir="rtl" selector="//*[@dir='rtl']"/>
 <its:dirRule dir="lro" selector="//*[@dir='lro']"/>
 <its:dirRule dir="rlo" selector="//*[@dir='rlo']"/>
 <its:locInfoRule locInfoType="alert"
   locInfoPointer="@locn-alert" selector="//*"/>
 <its:locInfoRule locInfoType="description"
   locInfoPointer="//@locn-note" selector="//*"/>
 <its:translateRule translate="yes" 
   selector="//*[@translate='yes']"/>
 <its:translateRule translate="no" 
   selector="//*[@translate='no']"/>

 <!--This rule is for the original XML Spec DTD-->
 <its:termRule selector="//term"/>

</its:rules>

Dojo 1.0

Dojo 1.0 contains the result of what how (primarily IBM) localization experts added localization support. The files holding the string localizations are expressed in JavaScript object literal notation, for example (showing Spanish):

({"buttonCancel": "Cancelar", "buttonSave": "Guardar", "buttonOk": "Aceptar"})

Here is the directory layout:

<dojoroot>/
    dojo/
       i18n.js (internationalition-related JavaScript logic)
       nls/
          color.js (English version of localization strings, expressed as JS object literal)
          fr/ ("fr" folder holds French translations)
             color.js
          etc. for other languages
    dijit/
       nls/
          dijit-all_en.js (sets flags for English currency format, date format, etc.)
          dijit-all_fr.js (sets flags for French currency format, date format, etc.)
          etc (for other currency format, date format, etc.)
          common.js (English version of common localization strings, expressed as JS object literal)
          loading.js (English version of another group of localization strings, expressed as JS object literal)
          fr/ ("fr" folder holds French translations)
             common.js
             loading.js
          etc. for other languages

Dojo's i18n.js file supports a high degree of flexibility for the language designations (e.g., "en" vs "us_en") with logic that implements RFC3066.

Dojo's source files do not contain the English language string, and instead contain the key that references the localized string, as in (notice "${buttonCancel}" below):

<button class='cancelButton' dojoAttachPoint="cancelButton" dojoType="dijit.form.Button" dojoAttachEvent="onClick:cancel">${buttonCancel}</button>

Analysis

Regarding the question about whether it is OK for the metadata files to include text values for localizable fields (e.g., include the English text in the base file), there is a strong convenience factor for many workflows to allow such text values:

• Some workflows only target a single language (and thus don't require localization)
• In many cases, the metadata files can be more understandable if text values are present
• For workflows that might be confused if text is present for localizable fields, they can always choose to leave the text field empty until the localization transforms occur

Jon's first proposed recommendation (which did not excite people at 20080103 phone call)

Let's just define an ITS rules file for each of the XML files that we define and claim victory.

If we want to keep the ITS rules file as small as possible, then we should do our best to put localizable fields into text nodes and non-localizable fields into attributes.

Regarding whether the metadata files are allowed to include text strings for localizable fields, my proposal is "yes", it is both allowed and optional. Developers can either include values in the original metadata file for localizable fields or not.

Even if everyone agrees with the above proposals, there are still some open questions. Do we want to define a standard place and format for the translation files? I would think we want to allow the widget developer to handle this in whatever way he wants. Maybe the biggest bang for the buck would be to provide a JavaScript hook such that the widget can register a JavaScript callback that gets invoked after the metadata file has been loaded, where the callback takes care of localization string substitutions.

Revised proposed recommendation

(waiting on minutes from 20080103 phone call)