Oracle® Fusion Middleware Platform Developer's Guide for Oracle Real-Time Decisions 11g Release 1 (11.1.1) E16630-05 |
|
Previous |
Localization of Inline Service metadata enables local language names to appear in the Rule Editor and Decision Center reports. The following Inline Service metadata elements can be localized: entities, entity attributes, choice attributes, and application parameters.
Note: This appendix concentrates on the main use of localization, that is, for localized entity and entity attribute names. |
This appendix contains the following topics:
Localization is achieved through a function which specifies the location where the source and target names (also known as messages) for the Inline Service metadata values are to be found. The source and target names may be listed in the function itself, but typically the names exist in a text file or database table. The function name is selected as the value for the application parameter Message Function. After Inline Service redeployment, localized text can now appear in Rule Editor screens and Decision Center reports.
Summarizing, there are three main factors required for setting up localization:
A source of localization messages (they can be in a text file inside the Inline Service or in a database)
A localization function to retrieve the localization messages
The localization function must be set as the application's Message Function parameter
The Inline Service must be edited in Decision Studio and deployed to the application server. The localized messages are then retrieved when users log into Decision Center.
Figure D-1 shows an example of the two standard ways to set up localization data, and the effect of localization on a Decision Manager report.
Figure D-1 Localization Setup and Decision Center Report Example
Note: While this appendix illustrates the effects of localization mainly on Decision Center reports, the impact is similar in Rule Editor screens: the Rule Editor screens will also display localized entity and entity attribute names. |
Whether specified within the localization function itself, in a text file, or in a database table, the localization data consists of corresponding pairs of source text strings and target text strings.
Source Text Strings
Source text strings derive from the internal IDs of Inline Service elements (and not the labels that typically appear by default in Inline Service screens).
Entity IDs are capitalized by default (for example, Address), and attribute and parameter IDs by default start with a lower-case character (for example, houseNumber). The IDs can be changed in Decision Studio, so it is important to see the ID values by clicking the Toggle icon, that toggles between showing labels and object IDs for object names.
An entity that is also an attribute of another entity has both an entity ID (when referenced as an explicit entity element) and an attribute ID (when referenced as an attribute of its encompassing entity). For example, if the Address entity is an attribute of Customer, the default explicit entity ID for Address is Address
, the default attribute ID for Address within Customer is Customer.address
.
For the examples that follow in this section, assume the Customer entity has the entity Address as one of its attributes, and Address has attributes street and houseNumber.
For general Inline Service elements, such as entities, the source text string format is:
<element_ID>
Examples: Customer
, Address, Offers
For attributes or parameters of general Inline Service elements, the source text string format is:
<element_ID>.<element_attribute_or_parameter_ID>
Examples: Customer.address
, Address.street,Offers
.profitMargin
For Application parameters, the source text string format is:
Application.
<parameter_ID>
Example: Application.serviceTest
For Session attributes, the source text string format is:
ApplicationSession.
<attribute_ID>
Example: ApplicationSession.customer
The special Inline Service elements Application and Session are not required as standalone source text strings for localization, they are handled internally by Oracle RTD.
Note: There can be no more than two dot-separated components to a source text string. For example, the following source text strings are invalid:
|
Target Text Strings
Target text strings are free-format text strings, typically, but not necessarily, in the local language. Target text strings can include spaces.
After localization is set up, the target text strings appear in the Rule Editor (in the lists of values and the conditions) and Decision Center reports.
Rule Editor Example
With source and target text strings such as:
ApplicationSession.ball=[BALL]
Ball=[BALL]
Ball.color=[COLOUR]
Ball.size=[SIZE]
the Rule Editor can render localized metadata in conditions, as in the following example:
The localization function is an Inline Service function with input parameter java.util.Locale
and which returns java.util.Map
or its subclasses (for example, java.util.Properties
).
Details of the source and target text strings appear in Section D.2, "Localization Source and Target Text Strings."
The returned map should contain pairs of source and target text strings. The map key is a source text string (such as Customer.address
) and is used to find the target text string (such as indirizzo
).
This section includes the following topics:
Section D.3.1, "Setup Example with Localization Data in Text Files"
Section D.3.2, "Setup Example with Localization Data in Database"
This scenario describes how to use the user browser language as the key to the localization message text files. For example, when the user browser language is set to English, the corresponding server locale may be set to en_US
(for US) or en_CA
(for Canada). The corresponding file name will be messages_en_US.properties
or messages_en.properties
if country-specific translation is not required.
The logic for looking up the appropriate file is as follows:
First, the full locale is used, for example, pt-BR (Portuguese - Brazil). The corresponding file name is messages_pt_BR.properties
.
If such a file is not found, only the language portion of locale is used: messages_pt.properties
.
If the file is not found, lookup logic falls back to the server's default locale (for example, en-US) and the above two steps are repeated.
If the file for the fallback locale is not found, the default file is used: messages.properties
.
As a last resort, an empty Map is returned to prevent Oracle RTD from continually asking for the localized messages if localization is not provided.
To implement the localization of the Inline Service metadata, perform the following steps:
As the Inline Service is deployed to the application server, all message files must propagate to the server's file system, that is, they must be deployed along with the Inline Service. For this, they must be in the Inline Service's dc/jsp
folder.
If that folder does not exist, create it in Decision Studio, as in the following example:
Create files in that folder, each with source and target text strings similar to the entries in the Text File example in Figure D-1.
Create the localization function.
In this example, the function is called Get Messages From Properties.
For the localization function:
Select Return value
For Data Type, select Other, then enter Properties for the Java Class Name
[Since the Inline Service function already imports java.util.* package there is no need to specify the full name of return type (java.util.Properties).]
Similarly, add the input parameter to the function, with java.util.Locale type.
Add code similar to the following to the function logic:
String language = locale.getLanguage(); String country = locale.getCountry(); Properties props = new Properties(); java.io.File appDir = com.sigmadynamics.sdo.loading.AppFactory.getInstance().getAppLocation( Application.getApp().getName(), Application.getApp().getDeploymentState()); java.io.File dcDir = new java.io.File(appDir, "dc/jsp"); Locale fallbackLocale = Locale.getDefault(); String fbLanguage = fallbackLocale.getLanguage(); String fbCountry = fallbackLocale.getCountry(); String fileName = "resources_" + language; if (!country.isEmpty()) fileName += "_" + country; fileName += ".properties"; java.io.File propFile = new java.io.File(dcDir, fileName); if (!propFile.exists()) { fileName = "resources_" + language + ".properties"; propFile = new java.io.File(dcDir, fileName); } if (!propFile.exists()) { fileName = "resources_" + fbLanguage; if (!fbCountry.isEmpty()) fileName += "_" + fbCountry; fileName += ".properties"; propFile = new java.io.File(dcDir, fileName); } if (!propFile.exists()) { fileName = "resources_" + fbLanguage + ".properties"; propFile = new java.io.File(dcDir, fileName); } if (!propFile.exists()) { fileName = "resources.properties"; propFile = new java.io.File(dcDir, fileName); } if (propFile.exists()) { try { props.load(new java.io.FileInputStream(propFile)); } catch (Exception e) { logError("Error retrieving localized messages from properties (locale [" +locale.toString()+"], file ["+propFile.getName()+"])", e); } } return props;
Assign this function as the Message Function for the application.
Redeploy the Inline Service.
Open the browser (in the following example, the browser is Internet Explorer) and add the desired language.
Move the new language to the top of the browser's Language Preference list.
After logging in to Decision Center, localized reports can be displayed, as shown in Figure D-1.
In this scenario, the localization data and locale information are stored in a database table. Any table and column names can be used.
In this example, the table name is LOCALIZATION, and it has columns LOCALE, SELECTOR (for the source text strings), MESSAGE (for the target text strings). It is also assumed that the database is the Oracle RTD database, with datasource SDDS.
To implement the localization of the Inline Service metadata, perform the following steps:
In the database, create the table by executing the following command:
CREATE TABLE LOCALIZATION ( LOCALE VARCHAR2(8) NOT NULL, SELECTOR VARCHAR2(200) NOT NULL, MESSAGE NVARCHAR2(2000) )
It is important for the target text column to have type NVARCHAR2 since the target text can be of any character set.
Enter data into the database table.
[This step can be performed now or later.]
Create the localization function, for example, Get Messages From Database.
For the localization function:
Select Return value
For Data Type, select Other, then enter Properties for the Java Class Name
Return type should be set to Map
Similarly, add the input parameter to the function, with java.util.Locale type.
Add code similar to the following to the function logic:
java.sql.Connection conn = null; java.sql.PreparedStatement pst = null; java.sql.ResultSet rs = null; Map<String, String> strings = new HashMap<String, String>(); try { conn = com.sigmadynamics.server.SDDataSource.getDataSource("SDDS").getConnection(); pst = conn.prepareStatement("select * from Localization where locale=?"); pst.setString(1, locale.getLanguage() + (locale.getCountry().isEmpty() ? "" : "_" + locale.getCountry())); rs = pst.executeQuery(); if (!rs.next()) { rs.close(); pst.setString(1, locale.getLanguage()); rs = pst.executeQuery(); } else { strings.put(rs.getString(2), rs.getString(3)); // selector + message } while (rs.next()) { strings.put(rs.getString(2), rs.getString(3)); // selector + message } } catch (Exception e) { logError("Error retrieving localized messages from database (locale ["+locale.toString()+"])", e); } finally { try { rs.close(); pst.close(); conn.close(); } catch (Exception e) {} } return strings;
Assign this function as the Message Function for the application.
Redeploy the Inline Service.
Perform the browser language setup steps (steps 9 and 10), described in Section D.3.1, "Setup Example with Localization Data in Text Files."
After logging in to Decision Center, localized reports can be displayed, as shown in Figure D-1.