This chapter provides required guidelines to internationalize Oracle E-Business Suite REST services and mobile apps. If your mobile users belong to different regions and prefer different languages, it is important to implement the mobile apps that can adapt to the user preferences.
Guiding Principles of Internationalizing Mobile Apps
When internationalizing mobile apps, you should consider the following:
When developing mobile apps, you must implement required formatting in the code for internationalization. All Oracle E-Business Suite mobile apps have to work properly in various locales and character sets. For example,
A Date value should be formatted differently for different locales.
User data should be handled correctly regardless of its character set.
User interface must be translated without having to change code.
Oracle E-Business Suite Mobile Foundation provides required infrastructure to implement internationalized mobile apps through its Login component. In some areas where an API is not available through the Login component, follow the guidelines described in this chapter to implement internationalization. For additional information, refer to Localizing MAF Applications, Developing Mobile Applications with Oracle Mobile Application Framework.
For information about the available languages in Oracle E-Business Suite mobile apps, see Setting Up and Using the Supported Languages, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2.
This chapter includes the following topics:
Data exchange between Oracle E-Business Suite mobile apps and the Oracle E-Business Suite server should be implemented using REST services. Before a mobile app begins to retrieve data from Oracle E-Business Suite or save data to Oracle E-Business Suite, the Login component initializes the required server sessions.
For information on the sequence of service invocation and how to test and validate the REST services, see Testing and Validating the REST Services.
Use the following guidelines to ensure that data exchange between Oracle E-Business Suite mobile apps and Oracle E-Business Suite are internationalized.
Data retrieved from Oracle E-Business Suite should be based on the session language initialized using the mobile device locale. This guarantees that when the data is displayed on a mobile app, it is translated as per device language preference.
Data encoding of the REST input and output messages should be UTF-8 to cover all Oracle E-Business Suite supported languages.
The REST input and output messages should follow the XSD standard. Locale sensitive data such as Date, Date Time, and Number types should be represented in appropriate canonical formats, as defined by the XSD standard (http://www.w3.org/TR/xmlschema11-2/#built-in-primitive-datatypes).
For datetime (type="xs:dateTime"), the ISO 8601 (http://www.w3.org/TR/NOTE-datetime) canonical format has to be used. For example, 2014-01-31T17:43:15Z (YYYY-MM-DDThh:mm:ss.sZ).
For Date type values, the mobile app should send the canonical Date string in the REST request to Oracle E-Business Suite. Similarly, Oracle E-Business Suite will return the canonical Date string in the REST response to the mobile app.
Locale sensitive data from Oracle E-Business should be formatted on the mobile app only based on the default format pattern and timezone set on the mobile device. Such data should not be formatted on the Oracle E-Business Suite server.
For handling currencies, the currency code should be in ISO 4217 format, such as USD
for US Dollar instead of a currency symbol $
, because the same currency symbol can be used for different currencies.
Additionally, the currency code, such as USD
, can be retrieved from the server but the corresponding amount value in the Number format should be retrieved from the server in the canonical format and then formatted on the mobile app based on device locale.
Oracle E-Business Suite REST service implementation should understand REST request values, such as Date, Date Time, and Number in the canonical format.
Important: Oracle E-Business Suite REST services provided through Oracle E-Business Suite Integrated SOA Gateway support REST request headers, such as the <NLSLanguage>
and <Language>
parameters, and other security context headers, such as the <Responsibility>
and <RespApplication>
parameters.
When Oracle E-Business Suite mobile apps invoke the REST services, do not pass values for the REST services. For mobile apps, it is only recommended that you use the Login component to initialize the server session with appropriate security context and language, but not through a specific REST request.
If Application Module-based REST services are used in your mobile apps, by default the Date value in a REST output is formatted as YYYY-MM-DD (for example, 2005-02-03) in which case the time part is 00:00:00 or as YYYY-MM-DD hh:mm:ss.s (1999-06-30 10:29:34.0). This is not the canonical ISO 8601 format. In order for Oracle MAF View Layer to display the Date value based on the device locale, the REST output should have Date value formatted in the ISO 8601 format.
To work around this issue, overwrite the underlying View Object's getter method as shown in the following example:
// Create a subclass of oracle.jbo.domain.Date. import org.w3c.dom.Document; import org.w3c.dom.Node; import oracle.jbo.domain.Date; public class DateISO extends Date { public DateISO(Date d) { super(d); } public Node getXMLContentNode(Document xmlDoc) { return xmlDoc.createTextNode(Util.formatISO8601(timestampValue())); } public int compareTo(Date date) { return super.compareTo(date); } } // Util. formatISO8601 method would be implemented in a utility class like this. private static final String ISO_CANONICAL_FORMAT_MASK = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"; private static final Locale ISO_CANONICAL_LOCALE = Locale.US; private static final TimeZone UTC_TIMEZONE = TimeZone.getTimeZone("UTC"); public static String formatISO8601(Date date) { SimpleDateFormat sdf = new SimpleDateFormat(ISO_CANONICAL_FORMAT_MASK, ISO_CANONICAL_LOCALE); sdf.setTimeZone(UTC_TIMEZONE); return sdf.format(date); } // Overwrite a ViewObject's getter method like this. From: public Date getHiredate() { return (Date)getAttributeInternal(HIREDATE); } To: public Date getHiredate() { if (getAttributeInternal(HIREDATE) != null) { return new DateISO((Date)getAttributeInternal(HIREDATE)); } else { return getAttributeInternal(HIREDATE); } }
A REST request message to Oracle E-Business Suite for a PL/SQL REST service could be like:
<?xml version="1.0" encoding="UTF-8" ?> <n0:notificationdetails_Input xmlns:n0="http://xmlns.oracle.com/apps/fnd/rest/mobileplsqlsample/notificationdetails"> <RESTHeader> <Responsibility /> <RespApplication /> <SecurityGroup /> <NLSLanguage /> <Org_Id /> </RESTHeader> <n0:InputParameters> <n0:NOTIFICATIONID>xxxxxxx</n0:NOTIFICATIONID> </n0:InputParameters> </n0:notificationdetails_Input>
A REST response message from Oracle E-Business Suite for the same PL/SQL REST service could be like:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <OutputParameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.oracle.com/apps/fnd/rest/mobileplsqlsample/notificationdetails/"> <NOTFDETAILS> <HEADER> <HEADER_ITEM> <NAME>Id</NAME> <VALUE>xxxxxxx</VALUE> <TYPE>TEXT</TYPE> </HEADER_ITEM> <HEADER_ITEM> <NAME>To</NAME> <VALUE>LAST_NAME, FIRST_NAME</VALUE> <TYPE>TEXT</TYPE> </HEADER_ITEM> <HEADER_ITEM> <NAME>Sent</NAME> <VALUE>2015-08-10T07:08:28Z</VALUE> <TYPE>DATA</TYPE> </HEADER_ITEM> <HEADER_ITEM> <NAME>Due</NAME> <VALUE>2016-08-09T07:08:28Z</VALUE> <TYPE>DATE</TYPE> </HEADER_ITEM> </HEADER> <DETAIL> <DETAIL_ITEM> <NAME>Document ID</NAME> <VALUE>APPROVAL_NOTIFICATION</VALUE> <TYPE>TEXT</TYPE> </DETAIL_ITEM> <DETAIL_ITEM> <NAME>Transaction Id</NAME> <VALUE>xxxxxx</VALUE> <TYPE>NUMBER</TYPE> </DETAIL_ITEM> <DETAIL_ITEM> <NAME>Process Display Name</NAME> <VALUE>Update to Offer</VALUE> <TYPE>TEXT</TYPE> </DETAIL_ITEM> <DETAIL_ITEM> <NAME>APPROVED</NAME> <VALUE>Approve</VALUE> <TYPE>TEXT</TYPE> </DETAIL_ITEM> </DETAIL> <RESULTS> <RESULTS_ITEM> <NAME>APPROVED</NAME> <VALUE>Approve</VALUE> <TYPE>TEXT</TYPE> </RESULTS_ITEM> <RESULTS_ITEM> <NAME>REJECTED</NAME> <VALUE>Reject</VALUE> <TYPE>TEXT</TYPE> </RESULTS_ITEM> </RESULTS> </NOTFDETAILS> </OutputParameters>
This section includes the following topics:
After creating an Oracle Mobile Application Framework project, configure the MAF application for internationalization:
In Oracle JDeveloper, right click the ApplicationController project, and then Project Properties.
Select Compiler and select "UTF-8" in the Character Encoding field from the drop-down list.
Select Resource Bundle and specify the following information:
Select the "Automatically Synchronize Bundle" check box to enable the feature.
Select the "Warn About Hard-coded Translatable Strings" check box to enable the feature.
Do not select the "Always Prompt for Description" check box.
Leave the default selection in the "One Bundle Per Project" button and the default project bundle name unchanged.
Leave the default value "Xliff Resource Bundle" unchanged in the Resource Bundle Type field.
The Project Properties Window
Right click the ViewController project, and then Project Properties.
Repeat the same tasks as described in step 1 to set the complier and resource bundle for the ViewController project.
For information on setting up an environment for internationalization, see Setting Up Oracle JDeveloper for Internationalization.
If an Oracle E-Business Suite mobile app is designed to be used in different languages, it is important to ensure that the content is translated to required languages without having to make any changes to the code. In order to translate the mobile app, follow the general translation principles supported by Oracle.
General Translation Principles
All information displayed to mobile app users, such as names, labels, and values must be translated. It includes:
UI component labels or values used in the AMX pages
Feature names in the maf-feature.xml
file
Application name in the maf-application.xml
file
Application preference labels in the maf-application.xml
file
Use XLIFF (XML Localization Interchange File Format) resource bundle to hold translatable strings and reference them in the User Interface elements as necessary.
The XLIFF file should be encoded in UTF-8.
All values retrieved from the Oracle E-Business Suite server through REST services to shown to users should be retrieved in the current session language.
All values coded in the mobile app that are shown to users should come from XLIFF resource bundle.
<!--AVOID THIS--> <amx:outputText value="Enter Username" id="ot6"/> <!--RECOMMENDED--> <amx:loadBundle basename="mobile.testPageBundle" var="viewcontrollerBundle" id="lb1" /> ... <amx:outputText value="#{viewcontrollerBundle.ENTER_USERNAME}" id="ot1" />
In order for the mobile apps to be translated correctly, consider the following guidelines:
Translation expansion.
Some languages require more space on average, compared with English text. Strings that are too long or screens that are already crowded in English may cause serious usability issues after translation, such as truncations and other layout issues. To avoid such issues, consider minimum space available for translation to be the length of the English text + 30% + 2 characters.
Text wrapping due to translation expansion should be weighed against a potential negative impact on user experience, by increasing the need for scrolling.
Characters (font) in several Asian languages tend to be taller than those in Latin-based languages.
Due to the limited display space in a mobile device, whole text may not be displayed. In this situation, one possible solution is to truncate a user interface label or text with ellipsis like "Label is truncat...".
This ellipsis highlights the cases where text overflows the available or designated space. You can rotate your mobile device to landscape mode to see the full text.
Avoid concatenating translatable messages, as this will adversely affect translation quality.
<!--AVOID THIS--> <amx:outputText value="#{bean.diskName} #{bundle.CONTAINS} #{bean.fileNumber} #{bundle.FILES}" id="it6"/>
Due to the limited display space in a mobile device, whole text may not be displayed. In this situation, one possible solution is to truncate a user interface label or text with ellipsis.
Examples of Truncated Label with Ellipsis
This ellipsis highlights the cases where text overflows the available or designated space. You can rotate your mobile device to landscape mode to see the full text.
Mobile Device in Landscape Mode with Full Text
Check the following style attributes to the component you want to have this truncation with ellipsis handling:
text-overflow: ellipsis;
overflow: hidden;
display: block; or (display: inline-block;)
white-space: nowrap;
max-width: 100% or (some other value). This attribute is needed some cases.
For example, like the field label case described earlier, you can get the field label truncation with ellipsis by setting the text-overflow: ellipsis;
attribute to the .amx-listItem .amx-outputText
style.
.amx-listItem .amx-outputText { text-overflow: ellipsis; }
Use the base XLIFF file which contains the source strings to generate the translated XLIFF files.
The translated XLIFF file name should adhere to the following naming conventions:
<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 the lower case ISO 639 two-letter language code and ISO 3166 two-letter country code if needed to identify the language, such as zh_TW (Traditional Chinese).
For example, for a base XLIFF named viewcontrollerBundle.xlf
, the translated XLIFF file names for English (Base), Korean, and Traditional Chinese languages are respectively:
English (Base xliff file, which is not translated): viewcontrollerBundle.xlf
Korean: viewcontrollerBundle_ko.xlf
Traditional Chinese: viewcontrollerBundle_zh_TW.xlf
Place the translated XLIFF files in the same directory as the corresponding base XLIFF file.
The REST output from Oracle E-Business Suite should be mapped to a Java object (such as canonical Date type value maps to a Java Date object, canonical Number type value maps to a Java Number object, etc.) based on the XSD associated with the REST output. No special handling is needed to get a Java object from the REST data.
Avoid formatting Date, Date Time, and Number types in the model layer using Java formatting, such as the following.
java.text.DateFormat
java.text.SimpleDateFormat
java.text.NumberFormat
java.text.DecimalFormat
Formatting Date, Date Time, Number should be done in the view layer (AMX layer).
Accessing XLIFF Resource Bundle
Use oracle.adfmf.util.BundleFactory.getBundle
to get the java.util.ResourceBundle
object, then call the ResourceBundle.getString
method.
ResourceBundle rb = BundleFactory.getBundle(“PATH.TO.RESOURCE.BUNDLE”); String errorMsg = rb.getString(“ERROR_MESSAGE”);
Use AMX and/or AMXF (AMX Page Fragment) to display content of a feature.
Avoid local HTML and remote URL, which could show locale sensitive data (Date, Date Time, Number) differently from the AMX/AMXF based pages.
Layout, Font, Text, and Style
Alignment should not be included in the code such as the inlineStyle
attribute or style sheet (CSS file) unless required in a special case to support BiDi languages. Avoid using the following style properties to have the horizontal alignment.
text-align
padding-left
padding-right
padding
margin-left
margin-right
margin
float
position
background-position
border-left
border-left-color
border-left-style
border-left-width
border-right
border-right-color
border-left-style
border-left-width
For example, avoid including "left" or "right" in the code for "text-align" in the inlineStyle
attribute.
<!--AVOID THIS --> <amx:outputText value="#{viewcontrollerBundle.HIRE_DATE}" inlineStyle="text-align:left;" id="it6"/>
Leave it blank in the "Text Align" property in the Style section of the Property Inspector panel.
Style Section with "Text Align" Property Highlighted
Avoid specifying "font-family" in the inlineStyle
attribute, as shown in the following example of incorrect usage.
<!--AVOID THIS --> <amx:outputText value="#{viewcontrollerBundle.HIRE_DATE}" inlineStyle="font-family:Tahoma;" id="it6"/>
Instead, leave it blank in the "Font Family" property of the Style section in the Property Inspector panel.
Style Section with "Font Family" Property Highlighted
Time-based Conversion and Formatting
In general, let MAF format a date, date time, or time with the default pattern. The default pattern changes depending on the mobile device locale setting. Avoid specifying a pattern as it may not work for certain languages or regions.
<!--RECOMMENDED --> <amx:outputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern=""/> <!-- No pattern was specified; default pattern is being used --> </amx:outputText> <!--AVOID THIS --> <amx:outputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern="yyyy-MMM-dd"/> <!-- DO NOT hard code pattern attribute --> </amx:outputText> <!--AVOID THIS --> <amx:outputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern="#{bindings.lastUpdateDate.format}"/> <!-- DO NOT pass a value to pattern attribute --> </amx:outputText>
If a fixed pattern is needed to meet specific business requirements, specify the required pattern as follows:
<!--OK --> <amx:outputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern="yyyy"/> </amx:outputText>
<amx:convertDateTime>
has the datestyle
and timestyle
attributes whose values are "full", "long", "medium", "short", etc. If no style is specified, the "short" style is used as a default. Set the proper style based on your business requirements.
<!--OK --> <amx:outputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern="" datestyle="long" timestyle="long" /> </amx:outputText>
Time-based Input and Date Picker
Use <amx:inputDate>
for date, datetime, and time data input with the date and time picker. Do not use <amx:inputText>
because this would need to be used in conjunction with <amx:convertDateTime>
, which is only supported for use with output.
<!--RECOMMENDED --> <amx:inputDate value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"/> <!--AVOID THIS --> <amx:inputText value="#{bindings.hireDate.inputValue}" label="#{viewcontrollerBundle.HIRE_DATE}" id="it6"> <amx:convertDateTime pattern=""/> </amx:outputText>
Use <amx:inputDate>
to format or parse date, datetime, or time, based on the device locale settings. <amx:inputDate>
does not have the pattern attribute, and cannot include <amx:convertDateTime>
.
Calendar
<amx:convertDateTime>
always uses the Gregorian calendar, regardless of the mobile device's calendar setting. In contrast, <amx:inputDate>
honors the mobile device's calendar setting.
The Gregorian calendar should be set for mobile client devices to avoid showing different calendar dates in the UI pages.
Timezone
The mobile device's timezone setting should be used.
Use <amx:outputText>
and <amx:convertDateTime>
for date, datetime, and time conversion and formatting. Use <amx:inputDate>
for date, datetime, and time data input. Depending on the mobile device's timezone setting, a date object is automatically converted to a formatted string.
Hour or 24 Hour Time Format
The mobile device's setting should be honored. Let AMF format the datetime or time so that the mobile device's setting is used.
Number Conversion and Formatting
Use <amx:convertNumber>
to format a number. Allow MAF to format the number with the default numeric characters (group and decimal separators). The default numeric characters would change based on the mobile device locale setting.
Numbers
Use <amx:outputText>
or <amx:inputText>
and set the "type" attribute to "number" (or do not specify type attribute value). Depending on your specific business requirements, the following attributes of <amx:convertNumber>
can be set for the number display except for currency number.
Grouping Used
Integer Only
Min Integer Digits
Max Integer Digits
Min Fraction Digits
Max Fraction Digits
<amx:inputNumberSlider>
can be used for number input.
Only the Gregorian calendar is supported in the device calendar setting. If you use a non-Gregorian calendar such as Japanese or Buddhist on an iOS device, you most likely will see a mixture of calendars in mobile app pages.
BiDi languages are not supported. Setting a BiDi language, such as Arabic or Hebrew, in the device setting is not supported.
On iOS, you need to set the same language for the iOS language and preferred language. Using different languages for the iOS language and preferred language could result in mixture language UI where UI labels are shown in the iOS language, whereas language data from Oracle E-Business Suite is shown in the preferred language.
The scope of Oracle E-Business Suite language support and the mobile device language support may be different. For example, iOS does not support Albanian and Slovenian, but Oracle E-Business Suite does.
If you have a MLS-enabled (multiple language support) Oracle E-Business Suite environment and you set your mobile device language to a language supported by Oracle E-Business Suite, but not in the languages listed as the supported languages for Oracle E-Business Suite mobile apps, then the data retrieved from the Oracle E-Business Suite server will be displayed in the mobile device specified language. However, the user interface labels within the app will appear in English.
If you set your mobile device language to a language not supported by Oracle E-Business Suite or not enabled in your Oracle E-Business Suite environment, then the data coming from the Oracle E-Business Suite server will be displayed in the Oracle E-Business Suite base language.
Supplementary characters are not supported because this is not supported by Oracle E-Business Suite.