Localizing an Application

Localizing an application involves the following steps:

• Externalize locale-dependent messages and settings in a properties bundle
• Load the properties
• Set the application locale
• Set and use properties
• Localize CDF GUI controls

Externalizing Messages and Settings

The first step towards internationalizing an application is to externalize all messages and settings that are locale-dependent. These are externalized as properties in a properties bundle. A properties bundle is a resource bundle where the type of resource is dynamic property. Properties bundle files contain locale-specific objects, such as menu and button labels in the application user interface.

Creating Properties Bundle Files

To create a new single-file formatted, properties bundle in the Properties Bundle editor in General Interface Builder, complete these steps:

1. Choose File > New > Properties Bundle to open the editor.
2. Right-click the table header in the editor and choose Add New Locale.
3. Type the key for the locale in the Add Locale dialog, such as en_US for US English or es for Spanish. For information on keys, see Locale Keys. Click OK.
   
   Click here to expand screenshot...
   
   
   
   
4. Click each Default cell and type the value for the default language. For example, for menu_new, type New.
5. Click each cell of the new locale column and type the value for the new locale. For example, for menu_new, type Cree for the Spanish locale.
   If a value is specified, the cell background is white. Otherwise, the inherited value from the next less-specific locale is shown in a gray cell.

   When authoring dynamic properties and properties bundle files using non-ASCII characters and non-western languages, save the file in a format that supports such characters, such as UTF-8 or UTF-16. See Character Encoding.

6. Save the file with the .xml extension in the jss folder of your project.

   Properties bundles can be authored in General Interface Builder in single-file format only. However, the multiple-file format may be more efficient for large collections of properties.

Loading Properties Bundle Files Automatically

To set the properties bundle file to automatically load when the application loads, complete the following steps in General Interface Builder:

1. Right-click the properties bundle file in the Project Files palette.
2. Choose Auto Load. The file now displays in a bold font in the Project Files palette.

Using Properties

Any property contained in a dynamic properties file or properties bundle and loaded by an application is available to the application in the following ways:

• Programmatically through the jsx3.app.Server.getProperties() method and the jsx3.app.Properties API. For example, the following statement:
  myApp.getProperties().get("prop_key1");
  evaluates to the value of the property, prop_key1, appropriate for the current locale of myApp.
• As dynamic properties of classes extending jsx3.gui.Painted. When a dynamic property of an instance of Painted is set, that property is expanded to the current value of the property stored in the server's properties object before the instance is painted.
  
  • A dynamic property of an instance of Painted can be set with the jsx3.gui.Painted.setDynamicProperty() method.
    
  • The Properties Editor palette in General Interface Builder allows you to assign dynamic properties to object properties. Right-click the Value cell of a property and select a dynamic property from the context menu or type the property key (ID) in the Value cell.

The Properties Editor palette also allows you to assign properties from a properties bundle file. To enter a property from a properties bundle file, type the property key (ID) in a Value cell of the Properties Editor palette.

Setting the Application Locale

The locale of an application is determined in the following order, with the first one taking precedence over the others:

1. The last value passed to Server.setLocale().
2. The default locale value specified in the Project Settings dialog and stored in the application configuration file (config.xml), if specified. See Deployment Panel.
3. The current system locale, which is specified by:
   
   1. The last value passed to System.setLocale()
      
   2. The locale as determined from the host browser
      
   3. en_US if the locale could not be determined from the browser

Default Locale

The locale as determined by the browser may not be the most appropriate locale for an application. If an application must always display in one locale, regardless of the user, use the Default Locale setting in the Project Settings dialog. See Deployment Panel.

Server.setLocale() Method

In some situations, specifying a default local isn't the best solution. In the following cases, use Server.setLocale() to set the locale:

• The user can choose a locale.
• The locale that the user wants is stored on a server.

Note that after the Server.setLocale() method is called, the state of the application may be out of synchronization with the new locale. Call the Server.reloadLocalizedResources() method to reload any localized properties that have already been loaded by the application. Additionally, the view of the application may have to be repainted.

The following sample code demonstrates how to use the Server.setLocale() method.

/**
    * Function is executed when user selects the language on the Tools menu.
    * @param objMenu {jsx3.gui.Menu}
    * @param strID {String} the CDF record ID of the execute menu record.
    */

    localization.doLoadLocalizeResource = function(objMenu, strID) {
      var objServer = localization.APP;

    var locale = strID != "-1" ? Locale.valueOf(strID) : null;

    LOG.info("Setting application locale to " + locale + ".");

    // Set the locale of the server to the selected locale
    objServer.setLocale(locale);

    // We need to tell the server to reload any localized properties
    objServer.reloadLocalizedResources();

    // Reset the CDF cache of the menu since dynamic properties are used
    // in the source XML file.

    objMenu.resetXmlCacheData();

    // Menus cache their drop-down HTML content, so clear this.
    objMenu.repaint();

    // Repaint the smallest region of the application that is localized.
    // Non-CDF control Stack with localized label text
    objServer.getJSXByName('blkApp').repaint();

  }

Localizing CDF GUI Controls

Some CDF attributes may have values that represent dynamic properties. These attributes must be of the form {key} where key is the key of a dynamic property of the control's server. If the dynamic property exists, the value of the attribute is changed to the value of the dynamic property when the XML source document is first loaded. Otherwise, the attribute is left unchanged.

For example, if you want to localize a menu using the properties bundle file, you would enter keys from the properties bundle file as the values for the jsxtext attributes, such as jsxtext="{menu_new}".

<data jsxid="jsxroot">
   <record jsxid="1" jsxtext="{menu_new\}"/>
   <record jsxid="2" jsxtext="{menu_open\}"/>
   <record jsxid="3" jsxtext="{menu_save\}"/>
</data>

Then, if the locale is Spanish, the following keys are replaced with the appropriate values in the properties bundle file:

• menu_new is replaced with Cree
• menu_open is replaced with Abra
• menu_save is replaced with Salve

The replacement of key attributes with the property value occurs only once per XML document. The CDF attributes that are converted automatically include: jsxtext, jsxtip, jsximg, jsxstyle, jsxclass, and jsxkeycode. After the conversion, which occurs before the control is painted, the original value of any key that has been converted is lost. Therefore, changing the value of a dynamic property after the conversion doesn't change the CDF attribute value. Do not set CDF attributes programmatically to a property key. Instead, set CDF attributes to the property value programmatically. You can also use the CDF.convertProperties() method to perform the conversion.

Custom Localized Logic

Applications may incorporate even more advanced localized functionality with custom localized code. Localized code would typically query the application server instance for its current locale and then modify its behavior based on the locale. This is a good strategy when localized behavior cannot be represented only as externalized string values.

In the following example, an alert displays on July 4 if the locale is US English.

var today = new Date();
if (myApp.getLocale.equals(jsx3.util.Locale.US) &&
   today.getMonth()h1. 7 && today.getDate()4) {
   myApp.alert("Holiday","Today is Independence Day");
}