12 Localizing UIM

Importing the Localization Archive File into Design Studio

The UIM_Home/cartridges/sample/ora_uim_localization_reference_cartproj.zip file contains an Inventory project with all of the UI-specific files that you can import into Design Studio to localize.

For instructions on how to import projects using archive files, see the Design Studio Help.

Locating the UI-Specific Files within the Project

The localization archive file that you imported into Design Studio contains the ora_uim_localization_reference project. The UI-specific files are contained within the project.

XLF Files

The UI-specific XLF files are located in the ora_uim_localization_reference project, within the model/content/inventory.ear/inv.war/WEB-INF/classes/oracle/communications directory. The communications directory contains the following subdirectories, which contain the UI-specific XLF files:

• inventory/ui/common/bundle/InventoryUIBundle.xlf

• inventory/ui/framework/bundle/InventoryOHWBundle.xlf

• platform/ui/CommsUIShell.xlf

• platform/ui/Preferences.xlf

Properties Files

The UI-specific properties files are located in the ora_uim_localization_reference project, within the model/content/product_home/config/resources/logging directory.

Copying and Renaming the UI-Specific Files

Copying and renaming the UI-specific files ensures that the default file is always in place to use for display if needed. Adding the locale to the file name differentiates your localized files from the default files, which simplifies upgrades. If files are edited for localization without being renamed to reflect the locale, all localization efforts are lost when you upgrade because the files are overwritten.

To copy and rename the files within the Design Studio Java perspective Package Explorer view:

1. Right-click on the file and select Copy.

2. Right-click on the parent directory of the copied file and select Paste.

   The Name Conflict dialog box appears.

3. Modify the file name to include the appropriate locale ID.

   For example, rename InventoryUIBundle.xlf to InventoryUIBundle_fr_ca.xlf and rename equipment.properties to equipment_fr_ca.properties for French spoken in Canada.

   See "Determining the Locale ID" for more information.

   Note:

   On the Add Language window shown in "Determining the Locale ID", the locale ID is separated by a dash. When renaming the XLF and properties files, use an underscore in place of the dash.

4. Click OK.

Editing the UI-Specific Files

To edit the UI-specific files, perform the work described in the following sections:

• Editing the XLF Files

• Editing the Properties Files

Editing the XLF Files

To edit the XLF files within Design Studio:

1. Open the Java perspective.

2. Open the Package Explorer view.

3. Within the imported project, locate the XLF files.

   See "Locating the UI-Specific Files within the Project" for more information.

4. Right-click on the file and select Open With, then select Text Editor.

   Caution:

   If you double-click on the file, Design Studio may open the file for editing outside of Design Studio.

5. Edit the value of the <source> elements, which define text that displays in the UI.

   Example 12-1 is an excerpt from the InventoryUIBundle.xlf file that shows numerous <source> elements. Edit only the value of the <source> elements: for example UIM Home Page, Inventory, Home, and Products.

   Example 12-1 InventoryUIBundle.xlf

   <trans-unit id="LANDING_PAGE_TITLE"> 
       <source>UIM Home Page</source>
       <target/>
   </trans-unit>
   <trans-unit id="MENU_INVENTORY">
       <source>Inventory</source>
       <target/>
   </trans-unit>
   <trans-unit id="MENU_HOME">
       <source>Home</source>
       <target/>
   </trans-unit>
   <trans-unit id="MENU_PRODUCT">
       <source>Products</source>
       <target/>
   </trans-unit>
   

   Note:

   The Preferences.xlf file defines a date format. If you want to localize the date format, see "XLF Files" for more information.

Editing the Properties Files

To edit the properties files within Design Studio:

1. Open the Java perspective.

2. Open the Package Explorer view.

3. Within the imported project, locate the properties files.

   See "Locating the UI-Specific Files within the Project" for more information.

4. Right-click on the file and select Open With, then select Text Editor.

   Caution:

   If you double-click on the file, Design Studio may open the file for editing outside of Design Studio.

5. Edit the text strings that define API messages that display in the UI.

   Example 12-2 is an excerpt from the party.properties file that shows two messages. Each message is defined by two lines: the first line defines the message ID, and the second line defines the message text that displays in the UI. Edit only the message text: for example, Party Id {0} already exists and The party with Id {0} was successfully deleted.

   Example 12-2 also shows that messages are not necessarily error messages; the partyDeleted message in is an informational message.

   Example 12-2 party.properties

   party.alreadyExists.id=230002
   party.alreadyExists=Party Id {0} already exists.
   party.partyDeleted.id=230009
   party.partyDeleted=The party with Id {0} was successfully deleted.
   

   For languages that have a heavy usage of single quotes like the French language, you use two single quotes in order to have the single quote show in the message. Example 12-3 has an example of using the two single quotes. This example results in the following message:

   • En attente d'attribution

   Example 12-3 Languages with Use of Single Quotes Need Two Single Quotes

   status.PENDING_ASSIGN=En attente d''attribution
   

   Note:

   UIM uses Java's MessageFormat class, which use a single quote to represent a pattern within the string. To have a single quote visible, you must use two single quotes to represent a single quote in the string.

   Most of the entries in the properties files are informational and error messages. Example 12-4 is a date format example where the value exists with a single line definition. This date format property is defined in the system.properties file.

   Example 12-4 system.properties Entry with a Date Format

   system.dateFormat=MM/dd/yyyy
   

   For the single-line property values that are not messages, the symbols must contain English abbreviations. For instance, French abbreviations for the date values

   MM/jj/aaaa
   

   create an error situation. Example 12-5 shows a property setting to accommodate a modified date display.

   Example 12-5 system.properties Entry with a Modified Date Format

   system.dateFormat=dd/MM/yyyy
   

About the Oracle Help Configuration File

The Oracle Help configuration file, ohwconfig.xml, is located in the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help directory. The ohwconfig.xml file contains references to each Help system deployed into an application. Upon installation, ohwconfig.xml references the default UIM Help system (English) deployed into UIM. This file requires configuration for localization.

About the UIM Help Files

The UIM Help files are located in the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help/helpsets/uimoh_help.jar file, which contains the following Help files:

• .htm files: Each HTML file is a separate Help topic. The text in all of the HTML files requires translation.

• uimoh.hs: This file describes the Help system. When UIM Help is initiated through the UIM user interface, uimoh.hs is the starting point. This file does not require translation.

• toc.xml: This file defines the Table of Contents that appears in the left pane of the Oracle Help window. The text in this file requires translation.

• map.xml: This file associates Help IDs with the HTML file names. The toc.xml file uses the IDs to link entries to Help topics. This file does not require translation.

• search.idx: This file is used when you perform a text search of the Help content. The file defines a search index that searches the Help content in the HTML files. After the HTML files are translated, the search index must be regenerated using the Java-based Help Indexer. For more information, see "Regenerating the Search Index File".

• target.db: This file contains cross-reference information used for navigating between Help topic headings. This file does not require translation.

• dcommon/html/cpyr.htm: This file defines the Help copyright page and requires translation. (The dcommon directory contains standard Oracle support files, including a CSS file, several graphics files, and the Help copyright page, but only the Help copyright page requires translation.)

Extracting the Help Files

Use the default Help files installed with UIM as the starting point for your localization.

To extract the Help files:

1. Copy the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help/helpsets/uimoh_help.jar file to tempDir, where tempDir is a local directory.

2. Open the tempDir/uimoh_help.jar file.

3. Extract all the objects in the uimoh_help.jar file into tempDir.

4. Click the File column heading in tempDir, which sorts the objects by file type.

   You should see the following directories and files in tempDir:

   • dcommmon directory

   • img directory

   • META-INF directory

   • target.db

   • uimoh_help.jar

   • uimoh.hs

   • numerous .htm files

   • search.idx

   • map.xml

   • toc.xml

Translating the Help Files

To translate the Help files, perform the work described in the following sections:

• Translating the Copyright Page

• Translating the Help Topics

• Translating the Table of Contents

Translating the Copyright Page

To translate the copyright page:

1. Navigate to the tempDir/dcommon/html directory.

2. Open the cpyr.htm file.

3. Translate the content of the <title>, <h1> through <h6>, and <p> elements to the local language.

   For example, translate the bolded content in Example 12-6:

   Example 12-6 Excerpt from cpyr.htm

   <title>Oracle Legal Notices</title>
   <link rel="stylesheet" href="../css/blafdoc.css" type="text/css" />
   </head>
   <body>
   <h1>Oracle Legal Notices</h1>
    
   <h2>Copyright Notice</h2>
   <p>Copyright &copy; 1994-2012, Oracle and/or its affiliates. All rights reserved.</p>
   

Translating the Help Topics

To translate the Help topics:

1. Navigate to the tempDir directory.

   The Help topics text is defined in the numerous .htm files within this directory. Each .htm file must be translated.

2. Open an .htm file.

3. Translate the content of the <title>, <h1> through <h6>, <p>, and <td> elements to the local language.

   For example, translate the bolded content in Example 12-7. Elements that are not text, such as the HTML tags themselves, should not be changed.

   Example 12-7 Excerpt from tel_nbr_info_work_area.htm

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <head>
   <meta name="OAC_IGNORE_SKIP_NAV" content="true" />
   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
   <meta http-equiv="Content-Style-Type" content="text/css" />
   <meta http-equiv="Content-Script-Type" content="text/javascript" />
   <title>Telephone Number - Information Work Area</title>
   <meta name="generator" content="Oracle DARB XHTML Converter (Mode = ohj/ohw) - Version 5.1.2 Build 073" />
   <meta name="date" content="2012-09-17T22:25:55Z" />
   <meta name="robots" content="noarchive" />
   <meta name="doctitle" content="Telephone Number - Information Work Area" />
   <meta name="relnum" content="Release 7" />
   <meta name="partnum" content="E36042-0" />
   <meta name="topic-id" content="telephoneInfo" />
   <link rel="copyright" href="./dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
   <link rel="stylesheet" href="./dcommon/css/blafdoc.css" title="Oracle BLAFDoc" type="text/css" />
   <link rel="contents" href="toc.htm" title="Contents" type="text/html" />
   </head>
   <body>
   <p><a id="CHDCJEIG" name="CHDCJEIG"></a><a id="telephoneInfo" name="telephoneInfo"></a></p>
   <div class="sect1"><!-- infolevel="all" infotype="General" -->
   <h1>Telephone Number - Information Work Area</h1>
   <p>You use the <span class="gui-object-title">Telephone Number - Information</span> work area to edit the information that appears in the Summary work area <span class="gui-object-title">Information</span> panel. Some data elements, such as the ID, cannot be changed after the entity is created.</p>
   <div align="center">
   <div class="inftblnote"><br />
   <table class="Note" summary="" cellpadding="3" cellspacing="0">
   <tbody>
   <tr>
   <td align="left">
   <p class="notep1">Note:</p>
   The fields that appear in this work area are determined by the entity specification definition used to create the entity. The specification is created in Design Studio. The fields defined below for this entity are common among most specifications.</td>
   </tr>
   

4. Repeat steps 2 and 3 for each .htm file in the tempDir directory.

Translating the Table of Contents

To translate the Table of Contents:

1. Navigate to the tempDir directory.

2. Open the toc.xml file.

   Each item in the Table of Contents is defined by a <tocItem> element.

3. Translate the content of each <tocItem> to the local language.

   For example, translate the bolded content of the text attribute in Example 12-8. Do not change the content of the target attribute.

   Example 12-8 Excerpt from toc.xml

   <tocitem target="uim_help_interface.htm" text="Getting Started with Unified Inventory Management">
   

Regenerating the Search Index File

After translating the Help files, regenerate the search index file to reflect the content of the translated files. This is accomplished using Oracle Help Indexer.

To install Oracle Help Indexer:

1. Go to the Oracle Technology Network website:

   http://www.oracle.com/technetwork/topics/utilsoft-085729.html

2. Download the help-indexer.jar file to tempDir, where tempDir is a local directory.

To regenerate the search index file using Oracle Help Indexer:

1. Open a Windows command prompt.

2. Change the directory to tempDir by entering the following command:

   cd tempDir
   

3. Enter the following command, which creates a new search.idx file, and overwrites the existing search.idx file:

   java -mx64m -classpath pathToJarFile/help-indexer.jar oracle.help.tools.index.Indexer -l=locale -e=charSet pathToHelpFiles search.idx
   

   where:

   • pathToJarFile is the directory path to the help-indexer.jar file.

   • locale is the standardized locale ID that represents the localized language. See "Determining the Locale ID" for more information.

     If you do not specify a locale, the system's default locale is used.

   • charSet is the Java-supported character set encoding.

   • pathToHelpFiles is the directory path to the Help files.

   For example:

   java -mx64m -classpath C:\tempDir\help-indexer.jar oracle.help.tools.index.Indexer -l=fr_CA -e=8859_1 C:\tempDir search.idx
   

   See Oracle Fusion Middleware Developing Help Systems with Oracle Help for more information on using the text search indexer:

   http://docs.oracle.com/middleware/1213/jdev/develop-help/toc.htm

Creating the Localized Help JAR File

After translating the Help files and regenerating the search index, create a new JAR file containing the localized Help files.

To create the new JAR file:

1. Navigate to the tempDir directory.

   The tempDir directory contains the uimoh_help.jar file, the translated Help files, and the regenerated search index file.

2. Copy the uimoh_help.jar file to tempDir to create a second copy of the uimoh_help.jar file in tempDir.

3. Select the copied version of the uimoh_help.jar file and rename it uimoh_help.jar_locale.jar, where locale is the standardized ID that represents a language and region in which the language is spoken. For example, fr-CA is the locale for French spoken in Canada, and es-MX is the locale for Spanish spoken in Mexico.

   For more information, see "Determining the Locale ID".

   Note:

   On the Add Language window shown in "Determining the Locale ID", the locale ID is separated by a dash. When renaming the JAR file, use an underscore in place of the dash.

4. Open the uimoh_help_locale.jar file.

5. Delete all of the objects in the JAR file.

6. Add the localized Help files to the uimoh_help_locale.jar file. (This includes all of the directories and all of the files in tempDir, with the exception of uimoh_help.jar and uimoh_help_locale.jar.

7. Save and close the uimoh_help_locale.jar file.

You can verify that you included all of the directories and files by checking the number of objects in the uimoh_help.jar file and in the uimoh_help_locale.jar file; the two JAR files should contain the same number of objects. To determine the number of objects in each JAR file, select all of the objects in each JAR file; this provides a count of all objects selected.

Configuring the Oracle Help File

After translating the Help files, regenerating the search index, and creating a localized Help JAR file, configure the ohwconfig.xml file to reflect the localized Help JAR file.

To configure the ohwconfig.xml file:

1. Open the UIM_Home/app/inventory.ear/inventory.war/WEB-INF/help/ohwconfig.xml file.

   The file defines the default Help system (English):

   <locales>
       <!-- English: -->
       <locale language="en">
           <books>
               <helpSet id="uimoh_help" 
                        jar="/helpsets/uimoh_help.jar" 
                        location="uimoh.hs"/>        
           </books>
       </locale>
   </locales>
   

2. Update the <locale> element to reflect the localized Help system:

   <locales>
       <!-- French Canadian: -->
       <locale language="fr">
           <books>
               <helpSet id="uimoh_help_fr_ca" 
                        jar="/helpsets/uimoh_help_fr_ca.jar" 
                        location="uimoh.hs"/>        
           </books>
       </locale>
   </locales>
   

You do not need to change the location attribute value, which is the name of the file that resides in the specified JAR file.

About Multiple Locales

Oracle Help can support multiple locales. For multiple locales, each localized Help system is configured with a <locale> element in the ohwconfig.xml file. For example, the following results in both French and Spanish Help systems being available in UIM upon redeployment:

<locales>
    <!-- French: -->
    <locale language="fr">
        <books>
            <helpSet id="uimoh_help_fr_ca"
                     jar="/helpsets/uim_oh_help_fr_ca.jar"
                     location="uimoh.hs"/>        
        </books>
    </locale>
</locales>
<locales>
    <!-- Spanish: -->
    <locale language="es">
        <books>
            <helpSet id="uimoh_help_es_mx" 
                     jar="/helpsets/uimoh_help_es_mx.jar" 
                     location="uimoh.hs"/>        
        </books>
    </locale>
</locales>
<parameters>
    <combineBooks>false</combineBooks>
    <useLabelInfo>true</useLabelInfo>
    <cacheSize>3</cacheSize>
</parameters>

When multiple locales are defined, the language preference for all locales must be set. If not set, only the first locale defined in the ohwconfig.xml file displays in UIM Help. See "Setting the Language Preference in Internet Explorer" for more information.

When multiple locales are defined, the <parameters> element configuration values are applied:

• <combineBooks>

  To merge Help systems, set the value of <combineBooks> to true. The Help navigational views behave as a single, integrated Help system.

  To use separate Help systems, set the value of <combineBooks> to false. The separate Help navigational views are accessed based on the language preference with the higher priority.

  Regardless of the <combineBooks> value, each locale that is defined in the ohwconfig.xml file must be specified as a language preference. See "Setting the Language Preference in Internet Explorer" for more information.

  Note:

  Oracle Help automatically translates the Help window menu options; field names; and informational, warning, and error messages. The translation is based on the first locale defined in the ohwconfig.xml file.

  For example, if the only language preference specified is English, and the ohwconfig.xml file defines the locales of French and Spanish, Oracle Help translates the Help window menu options, field names, and messages to French.

  However, when multiple locales are defined, the language preference for all locales must be specified. Otherwise, only the first locale defined in the ohwconfig.xml file displays in UIM Help. So, when the language preferences are set, Oracle Help translates the Help window menu options, field names, and messages to the language preference with the highest priority.

• <useLabelInfo>

  If <useLabelInfo> is set to true, author-defined labels are used for the navigators of merged Help systems.

  If <useLabelInfo> is set to false, default labels such as Contents, Index, and Search are used for the navigators of merged Help systems.

• <cacheSize>

  <cacheSize> indicates the number Help systems kept in memory at one time. The default value is 3.

For more information on the web configuration file, see Oracle Fusion Middleware Developing Help Systems with Oracle Help which you can find here:

http://docs.oracle.com/middleware/1213/jdev/develop-help/toc.htm