6 Localizing MAF Applications

This chapter describes how to use resource bundles where you can define text and image resources that render if your MAF application runs on devices that use multiple languages. The chapter also describes the design-time support that JDeveloper provides to create and edit resource bundles.

This chapter includes the following sections:

6.1 Introduction to MAF Application Localization

Localization is the process of making an application usable in one or more locales. For mobile applications, this generally means that your users use your MAF application in the same language as the mobile device they use. If, for example, your user's device sets French as the device language, the text resources of a localized MAF application appear in French.

MAF facilitates the localization process by providing design-time menus that enable you to define the text resources that appear in the user interface in one or more resource bundles. You define your MAF application's text resources in a base resource bundle. These text resources render in the user interface of the application on the user's device when your application does not include a locale-specific resource bundle for the locale of the device. You then create locale-specific resource bundles for each locale that you want to support. In these locale-specific resource bundles, you provide translations of the text resources that you defined in the base resource bundle.

Figure 6-1 shows an example where an application renders commandButton and outputText components. The text and image resources that appears in the components differ depending on the mobile device's language setting. On the left, the components renders a text resource in English because the base resource bundle contains text resources with English values and the device where the application runs uses English (or a language that is not French). On the right, the same components render text resources in French because the MAF application contains a local-specific resource bundle (_fr) with translations of the values in the base resource bundle and the mobile device's language setting is French.

Figure 6-1 Localized Text Resources

Surrounding text describes Figure 6-1 .

Consider using the following workflow if you intend to localize your MAF application:

  1. Determine the number of resource bundles in your MAF application, as described in Section 6.2, "Setting Resource Bundle Options for a MAF Application."

  2. Define the text resources in your base resource bundle that render when your MAF application runs in a locale that you do not provide a locale-specific resource bundle for.

    For more information, see Section 6.3, "Defining Text Resources in a Base Resource Bundle."

  3. Create locale-specific resource bundles where you provide translations of the text resources you defined in the base resource bundle.

    For more information, Section 6.4, "Creating Locale-Specific Resource Bundles."

  4. Create locale-specific versions of image files and other resources that you require to complete the localization of your MAF application.

    For more information, see Section 6.6, "Localizing Image Files in a MAF Application."

6.2 Setting Resource Bundle Options for a MAF Application

A MAF application's resource bundle(s) must use the XML Localization File format (XLIFF). JDeveloper creates an .xlf file resource bundle the first time that you enter a display value in the Select Text Resource dialog that you can invoke for each property that supports a localized value.

The default behavior is for a MAF application to have two resource bundles: one project-level resource bundle (default name ViewControllerController.xlf) and one application-level resource bundle. The naming convention for the application-level resource bundle is to use the application name and append Bundle.xlf. That is, a MAF application named MyLocalizedMAFapp has an application-level resource bundle named MyLocalizedMAFappBundle.xlf. The application-level resource bundle contains application-level text resources. For example, you specify the application name as a text resource in this resource bundle if you intend to translate the application name into different languages. Project-level resource bundles contain the text resources that render in the AMX pages of a project or the text resources of application feature properties. For more information about these properties, see Section 6.7, "Localizable MAF Properties."

You can change the default behavior of a MAF application having one project-level resource bundle by setting the resource bundle options for the project. A MAF application can have one application-level resource bundle only.

6.2.1 How to Set the Resource Bundle Options for a MAF Application

You set the resource bundle options for the view controller and application controller projects using the Resource Bundle page in the Project Properties dialog. Options that you can set include the number of project-level resource bundles that JDeveloper creates.

To set the resource bundle options for a project:

  1. In the Applications window, double-click the project.

  2. In the Project Properties dialog, select Resource Bundle to view the Resource Bundle page, as shown in Figure 6-2.

    Figure 6-2 Project Properties Resource Bundle Page

    This image is described in the surrounding text

  3. Select Always Prompt for Description if you want to prevent the Select Text Resource dialog from closing before you enter a description of the text resource in the dialog.

  4. Select one of the following resource bundle file options:

    • One Bundle Per Project —JDeveloper creates one resource bundle in a file named <ProjectName>.xlf.

    • One Bundle Per File— Creates a resource bundle each time you define a text resource for a file (maf-feature.xml, maf-application.xml, or an .amx file). 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.

  5. Click OK.

6.3 Defining Text Resources in a Base Resource Bundle

JDeveloper provides the Select Text Resource dialog where you can define values in resource bundles for MAF application, application feature, and AMX UI component text resources that appear to end users. You access the Select Text Resource dialog using the menu option that JDeveloper exposes for properties which can reference text resources defined in a resource bundle. These are typically properties that display text which users can see. Examples include the name properties for the MAF application and application features, in addition to the label, text, and hintText properties that AMX UI components such as command button, command link, and input text expose. For more information about these properties, see Section 6.7, "Localizable MAF Properties."

Figure 6-3 demonstrates how you display the Select Text Resource context menu for a MAF application's name, an application feature's name and an inputText component's Label property.

Figure 6-3 Context Menu to Display Select Text Resource Dialog

Surrounding text describes Figure 6-3 .

6.3.1 How to Define a Text Resource in a Base Resource Bundle

You define a text resource in a resource bundle using the Select Text Resource dialog which can be invoked for properties that reference text resources defined in resource bundles using EL expressions.

To define a text resource in a resource bundle:

  1. Choose the artifact that has a property for which you want to define a text resource. This could be the MAF application itself, an application feature or an AMX UI component.

  2. In the Properties window, click the icon beside the property for which you want to define a text resource and select Select Text Resource in the context menu that appears.

  3. In the Select Text Resource dialog, define a text resource by entering a display name, key, and then clicking Save and Select.

6.3.2 What Happens When You Define a Text Resource in a Base Resource Bundle

JDeveloper writes the display value and key that you enter to a resource bundle. If this is the first time that you define a text resource for a MAF application or project, JDeveloper creates the resource bundle. If the text resource that you define is for an application-level property (for example, the MAF application's name property), JDeveloper creates an application-level resource bundle (ApplicationNameBundle.xlf) that you can view in the Application Resources panel, as shown in Figure 6-4. If the text resource that you define is for a project-level property (for example, an application feature's name property), JDeveloper creates a project-level resource bundle (ViewControllerBundle.xlf) that you can view in the Projects panel, as shown in Figure 6-4.

Figure 6-4 Newly-Created Resource Bundles

Surrounding text describes Figure 6-4 .

JDeveloper creates one application-level resource bundle per MAF application but may create additional project-level resource bundles depending on the options that you set, as described in Section 6.2, "Setting Resource Bundle Options for a MAF Application."

The syntax of the XML that JDeveloper writes to the resource bundle for the key and display value is the same regardless of whether the resource bundle is an application or project-level resource bundle, as shown by the following example.

    ...
      <!-- The value of the id attribute is the value you enter in the Key input field of the
          Select Text Resource Dialog -->
      <trans-unit id="FEATURE_ONE">
      <!-- The value of the source element is the value you enter in the Display Value input 
          field of the Select  Text Resource Dialog -->
        <source>Feature Name</source>
        <target/>
      </trans-unit>
      <trans-unit id="HEADER_VALUE_IN_PANEL">
        <source>Header Value in Panel Page</source>
        <target/>
      </trans-unit>
      <trans-unit id="COMMAND_BUTTON">
        <source>Text Display Value for a Command Button</source>
        <target/>
      </trans-unit>
    ...

JDeveloper makes the changes shown in Example 6-1 for files where you configure a property to reference a text resource that you define in a resource bundle.

  • 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 changes the localized attribute string to an EL expression that refers to the key of the text resource defined in the resource bundle.

  • 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. At the project level, the behavior depends on the resource bundle settings you chose in Section 6.2, "Setting Resource Bundle Options for a MAF Application."

Example 6-1 Resource Bundle References in AMX Page and MAF Configuration Files

<!-- maf-application.xml where a text resource has been defined for the MAF application's name -->
        <adfmf:application ....name="#{mylocalizedmafappBundle.MY_LOCALIZED_MAF_APPLICATION}" 
        ...
                <adfmf:loadBundle basename="MyLocalizedMAFappBundle" var="mylocalizedmafappBundle"/>
 
<!-- maf-feature.xml where a text resource has been defined for the application feature's name -->
        <adfmf:loadBundle basename="mobile.ViewControllerBundle" var="viewcontrollerBundle"/>
        ...
                <adfmf:feature id="feature1" name="#{viewcontrollerBundle.FEATURE_ONE}">
 
<!-- AMX page where a text resource has been defined for a command button's text attribute -->
        <amx:loadBundle basename="mobile.ViewControllerBundle" var="viewcontrollerBundle" id="lb1"/>
        ...
     <amx:commandButton id="cb1" text="#{viewcontrollerBundle.COMMAND_BUTTON}"/>

6.4 Creating Locale-Specific Resource Bundles

You create a locale-specific resource bundle if you want your MAF application to render different text resources in a specific locale. If, for example, you want to provide translations of the text resources in the base resource bundle when the MAF application runs on a device that has the language set to French or Arabic, you need to create a locale-specific resource bundle for both the French and Arabic languages.

Figure 6-5 shows a MAF application where locale-specific versions of the application-level (MyLocalizedMAFappBundle.xlf) and project-level (ViewControllerBundle.xlf) resource bundles have been created to support the Arabic and French locales. You must create the locale-specific resource bundle in the same directory as the base resource bundle with a file name that uses the following format:

<BASE_RESOURCE_BUNDLE_NAME>_<LANGUAGE_TOKEN>.xlf

Where:

  • <BASE_RESOURCE_BUNDLE_NAME> is the base resource bundle name

  • <LANGUAGE_TOKEN> is in the following format: <ISO-639-lowercase-language-code>

    Note:

    MAF does not support countries or regions.

Figure 6-5 Base Resource Bundle and Locale-Specific Resource Bundles

Surrounding text describes Figure 6-5 .

6.4.1 How to Create a Locale-Specific Resource Bundle

JDeveloper facilitates the creation of project-level resource bundles by providing an option in the General > XML category of its New Gallery to create a new XML Localization File (XLIFF).

Alternatively, open the base bundle for which you want to create a locale-specific resource bundle and save a copy of the file with the appropriate language code in the file name. This latter option has the following benefits:

  • You create the locale-specific resource bundle in the same directory as the base resource bundle which is a requirement.

  • A copy of all text resources in the base resource bundle appear in the locale-specific resource base bundle where you can provide translated values.

To create a locale-specific resource bundle:

  1. Open the base resource bundle for which you want to create a locale-specific version:

    • Application-level base resource bundle: double-click the .xlf file in the Descriptors > ADF META-INF node of the Application Resources panel.

    • Project-level base resource bundle: double-click the .xlf file in the ViewController > Application Sources node of the Projects panel.

  2. In JDeveloper, click File > Save As and append the language code for the locale that you want to support.

    For example, append _fr if you want your MAF application to support the French locale.

  3. Edit the newly-created locale-specific resource bundle so that it includes the appropriate language codes.

    The following example demonstrates edits you need to make to support the French locale for an application-level and project-level resource bundle.

    <!-- Application-level French locale-specific resource bundle -->
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
  <file source-language="fr" original="this" datatype="x-oracle-adf">
 
<!-- Project-level French locale-specific resource bundle -->
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
  <file source-language="fr" original="mobile.ViewControllerBundle_fr"
                                                 datatype="x-oracle-adf">

  4. Edit the resource bundle to provide translations of each text resource that you want to appear in the target locale.

    For more information about editing resource bundles, see Section 6.5, "Editing Resources in Resource Bundles."

6.5 Editing Resources in Resource Bundles

JDeveloper provides an Edit Resources Bundle dialog where you can add, delete, or edit the resources in the resource bundles that a MAF application contains.

To edit text resources in a resource bundle:

  1. In JDeveloper, double-click the resource bundle where you want to edit text resources.

  2. In JDeveloper's main menu, choose Application > Edit Resource Bundles.

    The Edit Resource Bundles dialog opens for the resource bundle that you selected in Step 1. Figure 6-6 shows the dialog that opens for a French locale-specific resource bundle. Double-click in the Display Value and Description fields to edit existing text resources. Use the controls (Add, Delete, and Search) to add and remove text resources or to search for and open other resource bundles in the MAF application.

    Figure 6-6 Editing Text Resources in Resource Bundles

    Surrounding text describes Figure 6-6 .

  3. Click OK to close the dialog and save changes.

6.6 Localizing Image Files in a MAF Application

You may want to render different images file in a MAF application depending on the locale. For example, an image may contain text or a picture of a flag, as shown in Figure 6-7.

Figure 6-7 Rendering Different Images Based on Locale

Surrounding text describes Figure 6-7 .

Write an EL expression for the component attribute that references the image to an entry in the resource bundle. The resource bundle entry contains the path to the image. For example, the commandButton components shown in Figure 6-7 define the following value for the icon attribute in the AMX page that renders the components:

<amx:commandButton id="cb1" text="#{viewcontrollerBundle.YES}" 
                                      icon="#{viewcontrollerBundle.IMAGE_PATH}"/>

The base resource bundle (ViewControllerBundle.xlf) contains the following entry with the path to the image to appear when the MAF application runs in a locale that is not French.

<trans-unit id="IMAGE_PATH">
        <source>/images/uk.png</source>
        <target/>
        <note>Path to image file</note>
      </trans-unit>

The French resource bundle (ViewControllerBundle_fr.xlf) specifies a different image to render when the MAF application runs in a French locale, as shown in the following example.

<trans-unit id="IMAGE_PATH">
                <source>/images/fr.png</source>
                <target/>

Manually write the entries in the resource bundle that define the path to the image or use the Edit Resource Bundle dialog, as described in Section 6.5, "Editing Resources in Resource Bundles."

Once you have defined the path to the image in the source bundle, you can use the Expression Builder, as shown in Figure 6-8, to write an EL expression that references the entry in the resource bundle.

Figure 6-8 EL Expression Referencing an Image in a Resource Bundle

Surrounding text describes Figure 6-8 .

6.7 Localizable MAF Properties

The maf-application.xml and maf-feature.xml files both expose properties that can reference text resources in resource bundles. Table 6-1 and Table 6-2 list these properties. 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.

Table 6-3 lists the attributes of those MAF AMX UI components that can reference text resources.

At the application level, you can localize strings for such attributes as application name 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

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