Localizing Oracle BI Presentation Services

As the administrator, you perform various tasks to localize Oracle BI Presentation Services.

Topics include:

• Localizing the User Interface for Oracle BI Presentation Services

• Localizing Oracle BI Presentation Catalog Captions

• Tip for Arabic and Hebrew in Mozilla Firefox Browsers

Localizing the User Interface for Oracle BI Presentation Services

You can localize the user interface for Oracle BI Presentation Services, if your users speak languages other than English.

Users can select a language on the sign-in page for Oracle BI EE, and many elements of the interface are automatically displayed in the appropriate language. After signing in, users can change the language setting on the Preferences tab of the My Account dialog.

The user's setting is stored in the WEBLANGUAGE session variable. For the Oracle BI Presentation Services user interface, WEBLANGUAGE is set when a user selects a language on the sign-in page.

Note:

For Oracle BI Applications, WEBLANGUAGE is set to the language of the user's browser when a user logs in for the first time. For example, if a user with a browser language set to French logs in to Oracle BI Applications for the first time, then the value for WEBLANGUAGE is French, and the metadata is translated to French.

As the administrator, you perform various tasks to localize other elements of the user interface for Oracle BI Presentation Services, as described in the following sections:

• Understanding the Directory Structure for Localizing Presentation Services

• Localizing Messages for Users' Preferred Currency

• Specifying the Default Language for the Sign-In Page

• Configuring the Languages and Locales for the Sign-In Page

• Specifying the Language in the URL

Understanding the Directory Structure for Localizing Presentation Services

Oracle BI EE is installed with many files that control elements in the user interface and messages.

These files are installed in the messages and pages subdirectories of the ORACLE_HOME/bi/bifoundation/web/msgdb directory. To localize these elements and messages, you copy those files to the l_xx subdirectories in SDD/service_instances/service1/metadata/content/msgdb/l_xx

where SDD is the Singleton Data Directory, and _xx indicates the language extension. See Key Directories in Oracle Business Intelligence. After you have copied the files, you can modify their contents as appropriate for the language that corresponds to the subdirectory in which you have copied them.

Localizing Messages for Users' Preferred Currency

You can localize the messages that are associated with a preferred currency.

See Defining User-Preferred Currency Options Using a Static Mapping for information on working with users' preferred currencies.

1. Go to the SDD/service_instances/service1/metadata/content/msgdb/l_xx directory, where xx is the language extension for the language in which you are specifying preferred currencies.

   Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata. See Key Directories in Oracle Business Intelligence.

2. In the directory, create a subdirectory called custommessages.
3. In the directory, create a file in XML format, with the name of usercurrencymessages.xml.
4. Add entries such as the following one to this file for the language that corresponds to the directory in which you are working. The following example includes two messages: kmsgMyCurrency1 and kmsgMyCurrency2

   <?xml version="1.0" encoding="utf-8"?>
   <WebMessageTables xmlns:sawm="com.siebel.analytics.web/message/v1">
   <WebMessageTable system="CurrencyDisplay" table="Messages" code="false">
      <WebMessage name="kmsgMyCurrency1"><TEXT>My Currency Text 1</TEXT></WebMessage>
      <WebMessage name="kmsgMyCurrency2"><TEXT>My Currency Text 2</TEXT></WebMessage>
   </WebMessageTable>
   </WebMessageTables>
   

5. Edit the file to specify displayMessage="kmsgMyCurrency1" to use this message.
6. Repeat Steps 1 through 5 for each language for which you must localize these messages.
7. Restart the service for Oracle BI Presentation Services.

In Oracle BI EE, the appropriate localized text is displayed to the user. In this example, the text is My Currency Text 1.

Specifying the Default Language for the Sign-In Page

You can change the language the user sees by overriding the language specified by their browser.

The default language in which the Presentation Services sign-in page is displayed is obtained from the user's client browser settings. The following procedure explains how to change the language.

Note:

The following procedure uses Internet Explorer 7.0 as an example. If you are using a different browser, then make the necessary substitutions.

1. In Internet Explorer, from the Tools menu, select Internet Options.

   The Internet Options dialog is displayed.

2. Click Languages.

   The Language Preference dialog is displayed.

   Installed languages are displayed in the Language list. The language at the top of the list is used as the default language.

3. If the desired language is not installed on the browser, then add it.
4. Use the Move Up and Move Down buttons to position the desired language at the top of the list.
5. Restart the browser and sign into Presentation Services.

   The default language likely matches the language in the browser's Language list.

   Note:

   If a user does not select a different language from the list on the sign-in page, then the setting for the User Interface Language in the user's My Account dialog determines the language in which the user interface is displayed.

Configuring the Languages and Locales for the Sign-In Page

You can configure the languages and locales that are available to users on the sign-in page.

This ability is helpful for limiting the number of languages and locales that users can access. You use the AllowedLanguages and AllowedLocales elements in the instanceconfig.xml file to specify the available languages and locales.

Ensure that you are familiar with the information in Configuration Files before you start.

1. Open the instanceconfig.xml file for editing, located in:

   BI_DOMAIN/config/fmwconfig/biconfig/OBIPS

2. Locate the ServerInstance section, in which you must add the following elements:

   • AllowedLanguages — Specifies the languages that are available for selection, as a comma-delimited list. You can specify a list of the following identifiers, which are ISO 639 language codes:

     ar es da de el en es fi fr he hr hu it ja ko nl no pl pt pt-BR ro ru sk sv th tr zh-CN zh-TW

   • AllowedLocales — Specifies the locales that are available for selection, as a comma-delimited list. You can specify any definition from the localedefinitions.xml file in the ORACLE_HOME/bi/bifoundation/web/display directory. You specify the locales using ISO 639 language codes followed by ISO 3166 country codes. Examples include fr-fr and fr-ca.

3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

   <ServerInstance>
      <Localization>
         <AllowedLanguages>en,fr,pt-BR</AllowedLanguages>
         <AllowedLocales>en-ca,en-us</AllowedLocales>
      </Localization>
   </ServerInstance>
   

4. Save your changes and close the file.
5. Restart Oracle Business Intelligence.

Specifying the Scaling of Numbers in Performance Tiles

In Presentation Services, you can use performance tiles to focus attention on a single piece of high-level aggregate data.

The tile can include a number such 1,000,000 or you can specify to "compress" or "scale" the value with an indicator such as 1M, for example.

To scale the number, Presentation Services searches for the scaling factors that the current locale allows, processes the number, and appends the indicator value. If no scaling factors are defined for the current locale, then no scaling is applied. Because the scaling of numbers differs by language, you can manually edit the localedefinitions.xml file to control the scaling, as described in the following procedure.

1. In a text editor, open the localedefinitions.xml file in the directory:

   ORACLE_HOME/bi/bifoundation/web/display

2. In the file, add a new property for "scaleFactors" and enter values appropriate to your locale.

   The following shows values for an English locale:

   <localeDefinition name="en">
       <!-- existing data -->
           <property name="scaleFactors">
               <property name="thousand">K</property>
               <property name="million">M</property>
               <property name="billion">B</property>
               <property name="trillion">T</property>
               <property name="quadrillion">Q</property>
               <property name="quintillion">Qu</property>
               <property name="sextillion">S</property>
               <property name="septillion">Sp</property>
               <property name="octillion">O</property>
               <property name="nonillion">N</property>
               <property name="decillion">D</property>
               <property name="undecillion">UD</property>
               <property name="duodecillion">DD</property>
           </property>
   </localeDefinition>
   

   The following shows values for an Indian locale:

   <localeDefinition name="en-in" basedOn="en">
       <!-- english - india -->
       <!-- existing data -->
           <property name="scaleFactors">
               <property name="thousand">K</property>
               <property name="hundred-thousand">L</property>
               <property name="ten-million">Cr</property>
           </property>
   </localeDefinition>
   

3. Save your changes and close the file.
4. Restart Presentation Services.

See Editing Performance Tile Views in User's Guide for Oracle Business Intelligence Enterprise Edition.

Specifying the Language in the URL

When users start Oracle BI EE by displaying the sign-in page, they can select the language as part of the sign-in process.

Users can also select a language on the Preferences tab of the My Account dialog.

If you provide users with a URL with which they can display a dashboard or other page of the application, then you can define a URL parameter as a profile attribute. Doing so dynamically sets the language of the dashboards and analyses to be consistent with the application's language setting.

For operational applications, symbolic URLs embed dashboards and analyses in the integrated environment. For Oracle BI Presentation Services, the URL parameter Lang designates the language that the web page renders.

The Lang parameter can be included in the symbolic URL that is defined in the operational application to connect to Oracle Business Intelligence. The Lang parameter is defined as a profile attribute, but when the symbolic URL is constructed at runtime, the value is set as the profile attribute LanguageCode. The next table provides examples of the parameter settings in the Symbolic URL parameters applet, including Lang.

For example, the following URL displays the sign-in page in French.

http://Server_Name:port_number/analytics/saw.dll?Dashboard&Lang=fr

Name	Type	Path Argument Value	Append	Sequence #
Cmd	Constant	Go	Y	1
Path	Constant	/shared/Sales/Pipeline/Overview/Top 10 Deals	Y	2
nQUser	Command	UseLoginId	Y	3
nQPassword	Command	UseLoginPassword	Y	4
PostRequest	Command	PostRequest	Y	5
Lang	Profile Attribute	LanguageCode	Y	6

Localizing Oracle BI Presentation Catalog Captions

The Oracle BI Presentation Catalog stores objects that users create, such as analyses and dashboards. Text strings hold the names and descriptions of these objects.

If you must localize text strings for the objects, then you can export the text strings from the catalog so that they can be translated. You then expose the strings when translation is complete.

This section describes the steps in the process of localizing captions:

• Step 1: Understanding the Export Process

• Step 2: Exporting Text Strings in the Catalog

• Step 3: Editing Exported Strings in XML Files

• Step 4: Handling Duplicate Exported Text Strings

• Step 5: Exposing Text Strings in the Catalog

Step 1: Understanding the Export Process

The export process requires a series of steps that must be followed in order.

The export process creates one XML file for every first-level subfolder in the shared folder, in the format foldername captions.xml, where foldername is the name of the subfolder in the shared folder. Each XML file contains the text strings for all content in the corresponding first-level folder and its subfolders.

For example, if the shared folder in the Presentation Catalog contains the first-level folders Marketing, Service, and Sales, then the export process creates three XML files:

• marketingcaptions.xml

• salescaptions.xml

• servicecaptions.xml

After the content is translated, you place these folders in their corresponding location in the following directory:

SDD/service_instances/service1/metadata/content/msgdb/l_xx/captions

Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata (see Key Directories in Oracle Business Intelligence).

The export process not only generates new XML files, but the process also modifies the catalog, inserting the appropriate message ID for each object. Presentation Services uses those message IDs to locate the newly translated text.

Note that an error may occur when you export a folder whose name includes supplementary (extended Unicode) characters.

Step 2: Exporting Text Strings in the Catalog

The following procedure describes how to export text strings in the catalog.

1. Back up the catalog before exporting from it.

   Ensure that you run the export utility against the actual catalog, not against a copy of the catalog, because the export utility changes the properties of the objects in the catalog against which it runs.

2. In Catalog Manager, open the catalog in offline mode, because you might lack permission to modify all objects in online mode.
3. Select the folder that contains the strings to export. The utility runs against the files in that folder and all its subfolders.

   For example, the title (Another Report) in the analysis that is shown in the following illustration can be exported for translation.

   
   Description of the illustration GUID-3A981138-EB13-4C95-81AD-83ED4C4E4293-default.gif
4. From the Tools menu, select Export Captions.
5. Click Browse to select the location in which to write the output file, then click OK.
6. To export only new text strings and those that have been changed since the last export, select Only export new or changed strings.
7. To exclude the Description properties from the export, select Exclude Descriptions.
8. Click OK.

   The export process might take several minutes.

Step 3: Editing Exported Strings in XML Files

When the export process is complete, deliver the output XML file to the localization team.

When editing XML files, use an editor that is designed for XML files. Ensure that you follow the encoding that is specified at the top of the XML file and that you escape special characters as appropriate. You and the localization team are responsible for resolving any errors in the translated text strings. Consider that the contents of the catalog are updated whenever objects are added, deleted, or modified.

You can make a copy of every output file for each language to be translated.

The first illustration shows an extract from an exported caption XML file before translation. The file is named myfoldercaptions.xml. The second illustration shows an extract from the file after translation. The file is named myfoldercaptions_fr.xml.

Description of the illustration GUID-2AB750BB-C86F-4542-867E-E8E50F3418DA-default.gif

Description of the illustration GUID-09AADFCB-4DC7-4EAF-80CA-3737074FD0BC-default.gif

Step 4: Handling Duplicate Exported Text Strings

You might encounter an issue of having duplicate exported text strings from the catalog.

Duplicated exported text strings from the catalog happen when the Export Captions utility is run simultaneously by multiple users or if the same user runs the utility twice in less than one minute. The following procedure describes how to address duplicate captions.

The Export Captions utility is described in Step 2: Exporting Text Strings in the Catalog

1. Run the Export Captions utility.
2. In Catalog Manager, with the catalog still open in offline mode, select the folder that contains the strings to export.
3. From the Tools menu, select Export Captions.
4. Click Browse to select the location in which to write the output file, then click OK.
5. In the "What to do with duplicate captions" section, select one of the following options:

   • Create unique IDs even for identical strings — Specifies to create a unique ID for each instance of a string, even if the string is duplicated many times in the catalog. For example, suppose that a catalog includes the "Hello" string 1000 times. Use this option to specify that rather than generating one unique ID and translating the string only once, you want to instead generate 1000 unique IDs and translate the string 1000 times.

   • No, use the same ID for all identical strings — Specifies to create an ID for a string and use that same ID for all instances of that string. For example, suppose that a catalog includes the "Hello" string 1000 times. Use this option to specify that you want to generate one unique ID and translate the string only once, instead of generating 1000 unique IDs and translating the string 1000 times.

6. Click OK.

Consider the following webmessages.xml file, which contains duplicate captions:

<WebMessageTable system="catalog" type="folder" path="/shared/example/A">
    <WebMessage name="kcap12790830_5" use="Caption" status="new">
        <TEXT>A Really Good Report</TEXT>
    </WebMessage>
</WebMessageTable>
<WebMessageTable system="catalog" type="folder" path="/shared/example/B">
    <WebMessage name="kcap12790830_5" use="Caption" status="new">
        <TEXT>I like this report</TEXT>
    </WebMessage>
</WebMessageTable>
<WebMessageTable system="catalog" type="folder" path="/shared/example/Copy of A">
    <WebMessage name="kcap12790830_5" use="Caption" status="new">
        <TEXT>A Really Good Report</TEXT>
    </WebMessage>
</WebMessageTable>

In this example file, Object B has an invalid duplicate message ID. Object Copy of A has a valid but duplicate message ID. You can make the following selections in the Export Captions dialog:

• Selecting Leave alone makes no changes to the contents of the file.

• Selecting Remove IDs generates new and unique IDs for both Object B and Object Copy of A.

• Selecting Remove texts generates a new and unique ID for Object B and deletes the WebMessage element for Object Copy of A. While this option generally ensures fewer messages to translate, keep in mind that you now see two objects with the same name in a directory listing of the catalog in Presentation Services and in Catalog Manager.

Step 5: Exposing Text Strings in the Catalog

After you have exported the text strings for the catalog, you must expose them for users.

1. Place the translated XML files into their corresponding location in the following directory and restart Presentation Services:

   SDD/service_instances/service1/metadata/content/msgdb/l_xx/captions

   where SDD is the singleton data directory and xx is the language extension.

   For example:

   DOMAIN_HOME/bidata/service_instances/service1/metadata/content/msgdb/l_en/captions/myfoldercaptions_fr.xml

   Other examples of language extensions include cs for Czech and de for German.

   Note:

   The SDD/service_instances/service1/metadata/content/msgdb/l_xx/captions directory exists only if Oracle Business Intelligence Applications have been installed. If it does not exist, then you must create it.

   Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata .

2. The export process not only generates new XML files, but the process also modifies the catalog, inserting the appropriate message ID for each object. After placing the translated XML files in the directory as specified in Step 1, place the modified catalog in either its default location or in the appropriate location that the system now uses. See Key Directories in Oracle Business Intelligence for information.
3. Sign into Oracle Business Intelligence and select the appropriate language, such as French.
4. Display the translated content.

   For example, display the translated title in an analysis, as shown in the following illustration.

   
   Description of the illustration GUID-8EE3EAB6-A0A8-40A3-8709-75F08C83793D-default.gif

To move translated captions from a development environment to a production environment:

• If the caption file:

  • Does not exist in the production environment, then simply copy it from the development environment to the production environment.

  • Does exist in the production environment, first make a backup copy of the existing file. Then open the caption file in the production environment in a text editor or XML editing tool and manually (and very carefully) insert the changes that were made in the development environment.

Tip for Arabic and Hebrew in Mozilla Firefox Browsers

Right-to-left languages are displayed slightly differently in Mozilla Firefox browsers.

By default, scroll bars are displayed on the right side of the Mozilla Firefox browser. If you are using the Arabic or Hebrew languages, then it is not appropriate to have the scroll bars on the right side. You can change the browser settings in Firefox such that the scroll bars are displayed on the left side.

For information about changing the layout.scrollbar.side setting, see the Firefox documentation.