7 Localizing MAF Applications

This chapter describes using the MAF Application Editor and MAF Features Editor to define the display behavior of the mobile application's springboard and navigation bar and how to designate content by embedding application features.

This chapter includes the following sections:

Section 7.1, "Introduction to MAF Application Localization"

7.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 an 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 an 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).

OEPE supports automatic translation of these text resources into 28 languages. OEPE supports localization MAF components using the abstract class java.util.ResourceBundle, which provides locale-specific resources. While the support for localization is included in the OEPE MAF implementation, the design time editor does not support this automatically. You can enter the text strings manually for localization.

After you define translatable strings (such as validator error messages, or attribute control hints), Oracle Enterprise Pack for Eclipse 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 mobile application to store translatable UI strings at both the application and view project level.

7.1.1 Working with Resource Bundles

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

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

7.1.1.1 How to Enter a String in a Resource Bundle

At the project level, you create resource bundle files when you use the resource bundle dialog, accessed by opening the MAF Feature editor or MAF Application editor, then clicking the Externalize button next to the Name field. This opens the Externalize String dialog, which enables you to automatically create text resources in the base resource bundle for maf-application.xml and maf-feature.xml attributes listed in Table 7-1 and Table 7-2.

At the application level, you can use the MAF Application editor to localize strings for such attributes as application names or preference page labels, which are listed in Table 7-1.

Table 7-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 use the MAF Feature editor to localize application feature-related attributes listed in Table 7-2.

Table 7-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 MAF Feature editor, such as Name in Figure 7-1, and click Externalize. This opens the Externalize String dialog.
Select an existing property from the list and click OK.

Figure 7-1 Selecting the Edit Externalized String Dialog
In the Externalize String dialog, shown in Figure 7-2, create a new string resource by clicking Create a New Property. Enter a display value, a key, a description and then click OK.

Figure 7-2 Select Edit Externalized String Dialog

Note:
To edit an existing externalized string, select one from the list of existing properties and then click the pencil icon. This opens the Edit Externalized String dialog, from which you can change the value of the string and its description, but not the key.

7.1.1.2 What Happens When You Add a Resource Bundle

After you add a resource in the Select Text Resource dialog, Oracle Enterprise Pack for Eclipse creates a new project resource bundle containing the specified display name string and key file in the ADF Meta-INF file, as shown by mafapplication.xliff.

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

Oracle Enterprise Pack for Eclipse 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, Oracle Enterprise Pack for Eclipse 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.

Oracle Enterprise Pack for Eclipse 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.

7.1.1.3 How to Localize Strings in MAF AMX Components

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

Table 7-3 Localizable Attributes of MAF AMX 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 components:

Select an attribute in an AMX editor, such as the value attribute defined for the <amx:selectOneButton> component in Figure 7-3.

Figure 7-3 Externalizing Strings by Properties
Click the right mouse button and select Source > Externalize Strings. This opens the Externalize Strings dialog, shown in Figure 7-4.
In the Externalize Strings dialog, edit the string resources by entering a display name, key, and then click Finish.

Figure 7-4 Adding a String to a Resource Bundle

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

When you localize a component, such as the value attribute for a <amx:outputText> component in Example 7-1, Oracle Enterprise Pack for Eclipse transforms the string into an EL expression (such as #{viewControllerBundle.NewPage_header} in Example 7-1).

Example 7-1 Localizing an MAF AMX Component

<amx:facet name="header">
      <amx:outputText value="#{viewControllerBundle.NewPage_header}"
       id="ot1" />
    </amx:facet>

In addition, Oracle Enterprise Pack for Eclipse creates the resource bundle under the project default package, similar to ViewControllerBundle.xlf in Example 7-2. In the generated <amx:loadBundle> component, the basename represents this package.

Example 7-2 The <amx:loadBundle> Component

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

7.1.1.5 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, through the same XLIFF file process used for externalizing strings. See Figure 7-5.

Figure 7-5 Externalizing Images in the XLIFF File

This image is described in the surrounding text

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 7-3.

Example 7-3 Defining the Resource for an <amx:image> Component

<amx:image id="i1" source="#{viewControllerBundle.NewPage_icon2JPG}"
 shortDesc="#{viewControllerBundle.NewPage_myFavoriteImage}" />
         <trans-unit id="NewPage_icon2JPG">
             <source>/icon2.JPG</source>
             <target/>
         </trans-unit>
         <trans-unit id="NewPage_myFavoriteImage">
             <source>My Favorite Image</source>
             <target/>
         </trans-unit>
<trans-unit id="IMAGEPATH">
     <source>/feature1/test.jpg</source>
     <target/>
</trans-unit>

Note:

The image location defined in the <source> element in Example 7-3 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>.

After you update ViewControllerBundle.xlf, Oracle Enterprise Pack for Eclipse automates the construction of an EL expression for the source attribute for the icon attribute.

7.1.1.6 How to Edit a Resource Bundle File

After you have created the XLIFF file, or Java class file, you can edit it using the source editor. If you are using one of the MAF editors, you can invoke the Externalize command on the file.

7.1.1.7 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

7.1.1.8 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 7-2 and Table 7-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 7-4 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 7-4 shows an application feature with name, icon, and image attributes use internationalization strings.

Example 7-4 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 7-5, you create the mapping of bundle names to actual bundles. The bundle name is used when the expression is evaluated.

Example 7-5 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 7-6 illustrates the structure of the message sent to the JVM.

Example 7-6 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"}]]}