6 Localizing MAF Applications

This chapter describes how to configure a MAF application for use in a variety of locales and international user environments. Features such as JDeveloper's ability to automatically generate resource bundles, how you manually define resource bundles and locales in addition to configuring localization properties for your application are also described.

This chapter includes the following sections:

Section 6.1, "Introduction to MAF Application Localization"
Section 6.2, "Setting Resource Bundle Options"
Section 6.3, "What Happens When You Select Resource Bundle Options"
Section 6.4, "Entering a String in a Resource Bundle"
Section 6.5, "What Happens When You Add a Resource Bundle"
Section 6.6, "Localizing Strings in MAF AMX UI Components"
Section 6.7, "What Happens When You Create Project-Level Resource Bundles for MAF AMX UI Components"
Section 6.8, "What You May Need to Know About Localizing Image Files"
Section 6.9, "Editing a Resource Bundle File"
Section 6.10, "What You May Need to Know About XLIFF Files for iOS Applications"
Section 6.11, "What You May Need to Know About Internationalization for iOS Applications"

6.1 Introduction to MAF Application Localization

Localization is the process of adapting an application for a specific local language or culture by translating text and adding locale-specific components. By configuring the MAF application and its user interface pages to use different locales, you enable a MAF application to appear as though it has been authored for the language set on the mobile device. For example, if you intend to broaden the use of a MAF application by enabling it to be viewed by French speakers, you can localize the application so that its text strings and images used in both the device's springboard and within the MAF web view display in French (that is, products is transformed into les produits, and so on).

JDeveloper provides automatic translation of these text resources into 28 languages.

After you define translatable strings (such as validator error messages, or attribute control hints), JDeveloper stores them in a project-level resource bundle file. MAF specifies English language text resources (although you can use any tool to generate resource bundle files in other languages). You can configure a MAF application to store translatable UI strings at both the application and view controller project level.

MAF uses only XLIFF (XML Localization Interchange File Format) files for localization, meaning that JDeveloper produces resource bundle .xlf files to store the strings. For information on XLFF, see

http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html.

6.2 Setting Resource Bundle Options

You can create resource bundles for the view controller and application controller projects using Resource Bundle Settings page for projects, shown in Figure 6-1.

Figure 6-1 Project Properties Resource Bundle Page

This image is described in the surrounding text

To set the resource bundle options for a project:

In the Applications window, double-click the project.
In the Project Properties dialog, select Resource Bundle.
To automatically generate a default resource file, select Automatically Synchronize Bundle.
Select one of the following resource bundle file options:
- One Bundle Per Project —Configured in a file named <ProjectName>.xlf. For more information, see Section 6.3, "What Happens When You Select Resource Bundle Options."
- One Bundle Per File— Creates a new bundle each time you put a resource into file (maf-feature.xml, maf-application.xml or a MAF AMX page). As a result, each file has its own bundle. This option limits the number of resource bundles to one per file; if you select this option, JDeveloper prevents you from creating a second bundle.
Click OK.

Note:
Xliff Resource Bundle is the only resource bundle format used by MAF. For more information on this page, see the online help for Oracle JDeveloper.

6.3 What Happens When You Select Resource Bundle Options

JDeveloper generates one or more resource bundles of a particular type based on the selections that you make in the resource bundle options part of the Project Properties dialog, as illustrated in Figure 6-1. It generates a resource bundle the first time that you invoke the Select Text Resource dialog, as illustrated in Figure 6-3.

If you select One Bundle Per Project and the List Resource Bundle value from the Resource Bundle Type dropdown list. The first time that you invoke the Select Text Resource dialog, JDeveloper generates one resource bundle for the project.

By default, JDeveloper creates the generated resource bundle in the view subdirectory of the project's Application Sources directory.

6.4 Entering a String in a Resource Bundle

At the project-level, you create resource bundle files when you use the resource bundle dialog, accessed by clicking Select Text Resource in the Properties window. This dialog enables you to automatically create text resources in the base resource bundle for maf-application.xml and maf-feature.xml attributes listed in Table 6-1 and Table 6-2.

At the application level, you can localize strings for such attributes as application names or preference page labels, which are listed in Table 6-1.

Table 6-1 Localizable MAF Application Attributes

Element	Attribute(s)
`<adfmf:Application>`	`name`
`<adfmf:PreferenceGroup>`	`label`
`<adfmf:PreferencePage>`	`label`
`<adfmf:PreferenceBoolean>`	`label`
`<adfmf:PreferenceText>`	`label`
`<adfmf:PreferenceNumber>`	`label`
`<adfmf:PreferenceList>`	`label`
`<adfmf:PreferenceValue>`	`name`

At the project (view controller) level, you can localize application feature-related attributes listed in Table 6-2.

Table 6-2 Localizable Application Feature Attributes

Element	Attribute(s)
`<adfmf:Feature>`	`name`
`<adfmf:Constraint>`	`value`
`<adfmf:Parameter>`	`value`
`<adfmf:PreferencePage>`	`label`
`<adfmf:PrefrenceGroup>`	`label`
`<adfmf:PreferenceBoolean>`	`label`
`<adfmf:PreferenceText>`	`label`
`<adfmf:PreferenceNumber>`	`label`
`<adfmf:PreferenceList>`	`label`
`<adfmf:PreferenceValue>`	`name`

To create localized strings in a resource bundle:

Select an attribute in the Properties window, such as Name in Figure 6-2.
Choose Select Text Resource. Figure 6-2 shows the application name attribute selected in the Properties window.

Figure 6-2 Selecting the Text Resource Dialog
In the Select Text Resource dialog, shown in Figure 6-3, create a new string resource by entering a display name, key, and then click Save and Select.

Figure 6-3 Select Text Resource Dialog

6.5 What Happens When You Add a Resource Bundle

After you add a resource in the Select Text Resource dialog, JDeveloper creates a new entry in the .XLF file, as demonstrated in Example 6-1.

Example 6-1 Text Resource in a Resource Bundle

<?xml version="1.0" encoding="windows-1252" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
  <file source-language="en" original="mobile.ViewControllerBundle" datatype="x-oracle-adf">
    <body>
      <trans-unit id="ACME_SALES">
        <source>Acme Sales</source>
        <target/>
      </trans-unit>
    </body>
  </file>
</xliff>

If an attribute has been localized for the first time, JDeveloper adds an <adfmf:loadbundle> element whose basename attribute refers to the newly created resource bundle.

JDeveloper also changes the localized attribute string to an EL expression that refers to the key of the string defined in the resource bundle. For example, JDeveloper changes an application name attribute called Acme Sales to name="#{acmeBundle.Acme_Sales}" based on the ACME_SALES value entered for the Key in the Select Text Resource Dialog.

JDeveloper adds each additional string that you localize to the same resource bundle file because there is only one resource bundle file at the application level.

Each maf-application.xml and maf-feature.xml file contains only one adfmf:loadBundle element. When you deploy an application, the resource bundles are converted into the language format expected by the runtime.

6.6 Localizing Strings in MAF AMX UI Components

You can create resource bundles for attributes of such MAF AMX UI components as the text attribute of the Button component (<amx:commandButton>). Table 6-3 lists these MAF AMX UI components.

Table 6-3 Localizable Attributes of MAF AMX UI Components

Component	Attribute
`<amx:inputDate>`	`label`
`<amx:inputNumberSlider>`	`label`
`<amx:panelLabelAndMessage>`	`label`
`<amx:selectBooleanCheckBox>`	`label`
`<amx:selectBooleanSwitch>`	`label`
`<amx:selectItem>`	`label`
`<amx:selectManyCheckBox>`	`label`
`<amx:selectManyChoice>`	`label`
`<amx:selectOneButton>`	`label`
`<amx:selectOneChoice>`	`label`
`<amx:selectOneRadio>`	`label`
`<amx:commandButton>`	`text`
`<amx:commandLink>`	`text`
`<amx:goLink>`	`text`
`<amx:inputText>`	`label`, `value`, `hintText`
`<amx:outputText>`	`value`

To use strings in MAF AMX UI components:

Select an attribute in the Properties window, such as the value attribute defined for th Output Text (outputText) component in Figure 6-4.

Figure 6-4 Selecting a Text Resource for a MAF AMX Component
Choose Select Text Resource.
In the Select Text Resource dialog, shown in Figure 6-5, create a new string resource by entering a display name, key, and then click Save and Select

Figure 6-5 Adding a String to a Resource Bundle

6.7 What Happens When You Create Project-Level Resource Bundles for MAF AMX UI Components

When you localize a component, such as the value attribute of an Output Text (outputText) component in Example 6-2, JDeveloper transforms the string into an EL expression (such as #{viewcontrollerBundle.LES_PRODUITS} in Example 6-2).

Example 6-2 Localizing a MAF AMX Component

<amx:facet name="header">
      <amx:outputText value="#{viewcontrollerBundle.LES_PRODUITS}"
                      id="ot1"
                      rendered="true"/>
</amx:facet>

In addition, JDeveloper creates the resource bundle under the project default package, similar to ViewControllerBundle.xlf in Example 6-3. In the generated MAF AMX Load Bundle (loadBundle) component, the basename represents this package, as illustrated in Example 6-3.

Example 6-3 The Load Bundle (loadBundle) Component

<amx:loadBundle basename="mycomp.mobile.ViewControllerBundle"
                var="viewcontrollerBundle" 
                id="lb1"/>

6.8 What You May Need to Know About Localizing Image Files

If an image contains text or reflects a specific country or region (for example, a picture of a flag), you can specify an alternate image as part of the localization process. You cannot hard-code the image, such as icon="/feature1/test.png". Instead, you must edit the ViewControllerBundle.xlf file manually by adding a <trans-unit> element for the image path, as illustrated in Example 6-4.

Example 6-4 Defining the Resource for an <amx:image> Component

<trans-unit id="IMAGEPATH">
     <source>/feature1/test.jpg</source>
     <target/>
</trans-unit>

Note:

The image location defined in the <source> element in Example 6-4 is relative to the location of the application feature file in ViewController\public_html. Alternatively, you can enter the name of the image file, such as <source>test.png</source>. See also Section 5.4, "What You May Need to Know About Selecting External Resources."

After you update ViewControllerBundle.xlf, use the Expression Builder to define an EL expression for the source attribute for the icon attribute, as shown in Figure 6-6.

Figure 6-6 Creating the EL Expression for a Localized Icon Image

6.9 Editing a Resource Bundle File

After you have created the XLIFF file, you can edit it using the source editor.

To edit a resource bundle file:

From the main menu, choose Application > Edit Resource Bundles.
In the Edit Resource Bundles dialog, shown in Figure 6-7, select the resource bundle file you want to edit from the Resource Bundle dropdown list, or click the Search icon to launch the Select Resource Bundle dialog if the resource bundle file you want to edit does not appear in the Resource Bundle dropdown list.

Figure 6-7 Editing Resource Bundle Strings
In the Select Resource Bundle dialog, select the file type from the File type dropdown list. Navigate to the resource bundle you want to edit. Click OK.
In the Edit Resource Bundles dialog, click the Add icon to add a key-value pair, as shown in Figure 6-7. When you have finished, click OK.

6.10 What You May Need to Know About XLIFF Files for iOS Applications

One or more XLIFF files must exist at the location described by the <adfmf:loadBundle> element. A family of XLIFF files includes the following:

Base XLIFF File—The name of the base XLIFF file must match the last token in the path specified by the basename attribute. This file bears the .xlf extension, such as ViewControllerBundle.xlf. In the following definition, the file is called ViewControllerBundle:
```
<adfmf:loadBundle var="stringBundle" basename="view.ViewControllerBundle"/>
```
Zero, or more, localized XLIFF Files—There can be zero (or many) localized XLIFF files for each base XLIFF file. For each file:
- The file extension must be .xlf.
- Must be co-located in the same directory as the corresponding base XLIFF file.
- The file name is in the following format:
```
<BASE_XLIFF_FILE_NAME>_<LANGUAGE_TOKEN>.xlf
```
  Where:
  - <BASE_XLIFF_FILE_NAME> is the base XLIFF file name, without the .xlf extension.
  - <LANGUAGE_TOKEN> is in the following format:
```
<ISO-639-lowercase-language-code>
```
    Note:
    MAF does not support countries or regions.
    
    For example, for Spain, the language token is es.
  For example, localized file names for XLIFF files referencing a base XLIFF named stringBundle.xlf for language codes en, es, and fr would be:
  - stringBundle_en.xlf
  - stringBundle_es.xlf
  - stringBundle_fr.xlf

6.11 What You May Need to Know About Internationalization for iOS Applications

The localizable elements of the maf-application.xml and maf-feature.xml files reference internationalized strings through the use of EL-like strings in the attributes listed in Table 6-2 and Table 6-1. Because these configuration files are read early in the application lifecycle, these strings are not evaluated as EL statements at runtime. Instead, these strings are taken as the full key for the translated string in the native device translation infrastructure.

Although the Expression Language syntax is "${BUNDLE_NAME.STRING_KEY}", MAF uses the entire string enclosed by "#{}" as the key to look up the translated string. These strings are in the form of #{bundleName.['My.String.ID']}, where the XLIFF string is separated by periods and #{bundleName.['MyStringID']}, which is used only for string identifiers that are not separated by periods. Example 6-5 illustrates the latter, such as #{strings.CONTACTS}, that modify the name attribute. For the iOS native framework, the deployment ensures that the content of that statement matches the proper key in the *.string file used for translation.

Only the attributes that are displayed to the end user, or control the location of content displayed to the end user, support the use of internationalized strings. These include the following attributes:

The <adfmf:application> element's name attribute
The <adfmf:feature> element's name attribute
The <adfmf:feature> element's icon attribute
The <adfmf:feature> element's image attribute
The <adfmf:content> element's icon attribute
The <adfmf:content> element's image attribute

Example 6-5 shows an application feature with name, icon, and image attributes use internationalization strings.

Example 6-5 Internationalization Using Strings

<adfmf:feature id="CTCS" name="#{strings.CONTACTS}"  
                         icon="#{strings.CONTACTS_ICON}"
                         image="#{strings.CONTACTS_IMAGE}">
        <adfmf:constraints>
            <adfmf:constraint property="user.roles" 
                              operator="contains" 
                              value="employee" />
        </adfmf:constraints>
        <adfmf:description>The HTML Device Contacts</adfmf:description>
        <adfmf:loadBundle basename="mobile.adfmf-stringsBundle"
                          var="strings"/>
        <adfmf:content id="CTCS.Generic">
            <adfmf:constraints />
            <adfmf:localHTML url="contacts.html" />
        </adfmf:content>
  </adfmf:feature>

When you define the <adfmf:loadBundle> elements, as shown in Example 6-6, you create the mapping of bundle names to actual bundles. The bundle name is used when the expression is evaluated.

Example 6-6 Mapping Bundle Names Using <adfmf:loadBundle>

   <adfmf:constraints>
      <adfmf:constraint property="user.roles"
                        operator="contains"
                        value="employee" />
   </adfmf:constraints>
        <adfmf:description>The HTML Device Contacts</adfmf:description>
        <adfmf:loadBundle basename="mobile.adfmf-featureBundle" 
                          var="mobileBundle"/>
        <adfmf:loadBundle basename="mobile.adfmf-stringsBundle" 
                          var="strings"/>

MAF's runtime holds the <adfmf:loadBundle> elements until it first accesses the JVM. It sends a message to the JVM to initialize the mapping of the base names of the packages to EL names of the bundles. Example 6-7 illustrates the structure of the message sent to the JVM.

Example 6-7 The Message Initializing Mapping of Base Names to EL Names

{classname:"oracle.adfmf.framework.api.Model",method:"setBundles",
 params:[[{basename:"mobile.adfmf-featureBundle",elname:"mobileBundle"},
          {basename:"mobile.adfmf-stringsBundle",elname:"strings"}]]}