D Localization of Inline Service Metadata

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:

D.1 Localization Overview

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

Description of Figure D-1 follows
Description of "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.

D.2 Localization Source and Target Text Strings

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:

  • Customer.Address (Second value must be an attribute ID)

  • Customer.Address.street (Second value must be an attribute ID, and only two values allowed)

  • Customer.address.houseNumber (Only two values allowed)

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:

Description of img_005.png follows
Description of the illustration img_005.png

D.3 Setting Up Inline Service Localization

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:

D.3.1 Setup Example with Localization Data in Text Files

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:

  1. 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:

    Description of img_007.png follows
    Description of the illustration img_007.png

  2. 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.

    Description of loc_dcjsp.gif follows
    Description of the illustration loc_dcjsp.gif

  3. Create the localization function.

    In this example, the function is called Get Messages From Properties.

  4. For the localization function:

    [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).]

  5. Similarly, add the input parameter to the function, with java.util.Locale type.

  6. 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;

  7. Assign this function as the Message Function for the application.

    Description of img_015.png follows
    Description of the illustration img_015.png

  8. Redeploy the Inline Service.

  9. Open the browser (in the following example, the browser is Internet Explorer) and add the desired language.

    Description of img_017.png follows
    Description of the illustration img_017.png

  10. Move the new language to the top of the browser's Language Preference list.

    Description of img_019.png follows
    Description of the illustration img_019.png

After logging in to Decision Center, localized reports can be displayed, as shown in Figure D-1.

D.3.2 Setup Example with Localization Data in Database

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:

  1. 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.

  2. Enter data into the database table.

    [This step can be performed now or later.]

    Description of loc_db2.gif follows
    Description of the illustration loc_db2.gif

  3. Create the localization function, for example, Get Messages From Database.

  4. 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

  5. Similarly, add the input parameter to the function, with java.util.Locale type.

  6. 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;

  7. Assign this function as the Message Function for the application.

  8. Redeploy the Inline Service.

  9. 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.