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 OEPE 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 adapting a product to a specific locale. With localization, a MAF application uses the same language as the mobile device on which it is deployed. For example, if French is set 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 for the definition of text resources that appear on the user interface in one or more resource bundles. Define your MAF application's text resources in a base resource bundle. If your application does not include a locale-specific resource bundle for the locale of the device, these text resources are rendered on the user interface of the application on the user's device. Create locale-specific resource bundles for each locale to be supported. In these locale-specific resource bundles, provide translations of the text resources that you had 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 vary depending on the language set on the mobile device. On the left, the components render 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 locale-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

This image is described in the surrounding text

Use the following steps 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 to be rendered when your MAF application runs in a locale for which you do not provide a locale-specific resource bundle.

    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 that you had 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 are needed 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 bundles use the XML Localization File format (XLIFF). OEPE creates a .xlf file resource bundle the first time that you enter a display value in the Externalize String dialog. Invoke Select Text Resource for each property that supports a localized value.

By default, a MAF application has two resource bundles:

  • A project-level resource bundle (default name ViewControllerController.xlf)

  • An application-level resource bundle (default name mafapplication.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 to translate the application name into different languages. Project-level resource bundles contain the text resources that render in the MAF AMX pages of a project, or the text resources of application feature properties. For more information about these properties, see Section 6.8, "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 only have one application-level resource bundle.

6.3 Defining Text Resources in a Base Resource Bundle

OEPE provides the Externalized String dialog where you can define values in resource bundles for a MAF application, application feature, and MAF AMX UI component text resources that appear to end users. Access the Externalized String dialog by clicking the icon beside the property for which you want to define a text resource in the MAF Application Editor or MAF Features Editor. These properties 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 MAF AMX UI components such as button, link, and input text expose. For more information about these properties, see Section 6.8, "Localizable MAF Properties."

Figure 6-2 demonstrates how you display the Externalize context menu for a MAF feature's name. The same button is used for an application feature's name.

Figure 6-2 Selecting the Edit Externalized String Dialog

This image is described in the surrounding text

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

To use strings in MAF AMX components:

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

    Figure 6-3 Externalizing Strings by Properties

    The surrounding text describes this image.

  2. Click the right mouse button and select Source > Externalize Strings. This opens the Externalize Strings dialog, shown in Figure 6-4.

  3. In the Externalize Strings dialog, edit the string resources by entering a display name, key, and then click Finish.

    Figure 6-4 Adding a String to a Resource Bundle

    The surrounding text describes this image.

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 Externalize String 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 a MAF AMX UI component.

    For example, an attribute in the MAF Feature editor, such as Name in Figure 6-2, and click Externalize. This opens the Externalize String dialog.

  2. In the Externalize String dialog, shown in Figure 6-5, create a new string resource by clicking Create a New Property. Enter a display value, a key, a description and then click OK.

    The first time you create a new string resource and save the workspace, the resource file is created. When you subsequently open the Externalize String dialog, there is a link to the resource file.

    Figure 6-5 Select Edit Externalized String Dialog

    This image is described in the surrounding text

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

OEPE 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, OEPE 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), OEPE creates an application-level resource bundle (mafapplication.xlf). If the text resource that you define is for a project-level property (for example, an application feature's name property), OEPE creates a project-level resource bundle (ViewControllerBundle.xlf), as shown in Figure 6-6.

Figure 6-6 Newly-Created Resource Bundles

This image is described in the surrounding text

OEPE creates one application-level resource bundle and one project-level resource bundle per MAF application.

The syntax of the XML that OEPE 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>
    ...

OEPE makes the changes shown in Figure 6-6 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, OEPE adds an <adfmf:loadbundle> element whose basename attribute refers to the newly created resource bundle.

  • OEPE changes the localized attribute string to an EL expression that refers to the key of the text resource defined in the resource bundle.

Example 6-1 Resource Bundle References in MAF 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}">
 
<!-- MAF 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. For example, if 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-7 shows a MAF application where the locale-specific versions of the application-level (mafapplication.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>

    For a list of the languages that MAF supports, see Section 6.7, "MAF Support of Languages."

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

This is described in the surrounding text

6.4.1 How to Create a Locale-Specific Resource Bundle

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 allows you to:

  • 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: in the assembly project, double-click the .xlf file in the ADF > META-INF node.

    • Project-level base resource bundle: in the view project, double-click the .xlf file in the src > mobile node.

  2. In OEPE, 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

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.

6.6 Localizing Image Files in a MAF Application

You may want to render different image files 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-8.

Figure 6-8 Rendering Different Images Based on Locale

This image is described in the surrounding text

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-8 define the following value for the icon attribute in the MAF 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.

Once you have defined the path to the image in the source bundle, you can use the Expression Builder. For more information, see Section 13.3.2, "How to Create an EL Expression."

6.7 MAF Support of Languages

Figure 6-1 lists the languages that are supported by MAF. System messages, such as error messages, appear in these languages if the user's device is configured to use one of these languages. MAF supports language tokens for countries and regions. However, full support is only available to the extent that they appear in the list of languages. Error messages from MAF use the closest of languages provided in the list. The language is usually English unless the device is configured to use one of the languages in the table, or a more specific variant of one of these languages.

If you want an application to render additional resource strings in these languages, you must define them. Create a locale-specific resource bundle using the language token listed in Table 6-1. For example, to define resource strings for Brazilian Portuguese, create a resource bundle named BASE_RESOURCE_BUNDLE_NAME_pt_BR.xlf. To create resource bundles for languages that are not included in the list, create resource bundles with the following name format: BASE_RESOURCE_BUNDLE_NAME_lowercase-ISO-639-1-language-code.xlf. For more information about the naming convention, see Section 6.4, "Creating Locale-Specific Resource Bundles."

During deployment, OEPE transforms the language tokens to the expected values on the platform on which the application is deployed. For example, a MAF application that you deploy on the iOS platform transforms the language token pt_BR to pt, the expected language ID on the iOS platform.

Table 6-1 Resource Bundle Names for Languages Supported by MAF

Language Resource bundle name to provide additional UI strings

Arabic

BASE_RESOURCE_BUNDLE_NAME_ar.xlf

Brazilian Portuguese

BASE_RESOURCE_BUNDLE_NAME_pt_BR.xlf

Catalan

BASE_RESOURCE_BUNDLE_NAME_ca.xlf

Czech

BASE_RESOURCE_BUNDLE_NAME_cs.xlf

Danish

BASE_RESOURCE_BUNDLE_NAME_da.xlf

Dutch

BASE_RESOURCE_BUNDLE_NAME_nl.xlf

Finnish

BASE_RESOURCE_BUNDLE_NAME_fit.xlf

French

BASE_RESOURCE_BUNDLE_NAME_fr.xlf

German

BASE_RESOURCE_BUNDLE_NAME_de.xlf

Greek (Modern)

BASE_RESOURCE_BUNDLE_NAME_el.xlf

Hebrew

BASE_RESOURCE_BUNDLE_NAME_iw.xlf

Hungarian

BASE_RESOURCE_BUNDLE_NAME_hu.xlf

Italian

BASE_RESOURCE_BUNDLE_NAME_it.xlf

Japanese

BASE_RESOURCE_BUNDLE_NAME_ja.xlf

Korean

BASE_RESOURCE_BUNDLE_NAME_ko.xlf

Norwegian

BASE_RESOURCE_BUNDLE_NAME_no.xlf

Polish

BASE_RESOURCE_BUNDLE_NAME_pl.xlf

Portuguese

BASE_RESOURCE_BUNDLE_NAME_pt.xlf

Romanian

BASE_RESOURCE_BUNDLE_NAME_ro.xlf

Russian

BASE_RESOURCE_BUNDLE_NAME_ru.xlf

Simplified Chinese

BASE_RESOURCE_BUNDLE_NAME_zh_CN.xlf

Slovak

BASE_RESOURCE_BUNDLE_NAME_sk.xlf

Spanish

BASE_RESOURCE_BUNDLE_NAME_es.xlf

Swedish

BASE_RESOURCE_BUNDLE_NAME_sv.xlf

Traditional Chinese

BASE_RESOURCE_BUNDLE_NAME_zh_TW.xlf

Turkish

BASE_RESOURCE_BUNDLE_NAME_tr.xlf

Thai

BASE_RESOURCE_BUNDLE_NAME_th.xlf

6.8 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-2 and Table 6-3 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-4 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-2.

Table 6-2 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 6-3.

Table 6-3 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>). Figure 6-4 lists these MAF AMX UI components.

Table 6-4 Localizable Attributes of MAF AMX UI Components

Component Attribute(s)

<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