This chapter includes the following sections:
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
Use the following steps to localize your MAF application:
Determine the number of resource bundles in your MAF application, as described in Setting Resource Bundle Options for a MAF Application.
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 Defining Text Resources in a Base Resource Bundle.
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, Creating Locale-Specific Resource Bundles.
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 Localizing Image Files in 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 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.
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 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
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:
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:
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
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 the example below 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.
<!-- 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}"/>
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 MAF Support of Languages.
Figure 6-7 Base Resource Bundle and Locale-Specific Resource Bundles
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:
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.
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
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 How to Create an EL Expression.
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 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 |
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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|