This chapter provides information on localizing the Oracle Communications Unified Inventory Management (UIM) user interface (UI), and on localizing the UIM Help. Localization is the process of translating a UI or Help system from the original language in which it was written into a different language for use in a specific country or region. For example, the UIM UI and UIM Help are written in English. If your company is based in France and you purchase UIM, you may want to localize UIM to display the UI and Help in French.
Localizing UIM involves modifying a specific set of files that UIM uses to display text in the UI and in the Help.
Note:
Before localizing your UIM environment, you must identify a strategy for maintaining future localizations. Oracle does not provide a file that lists the details of what changed between releases.
For a localized version of UIM to display correctly in Internet Explorer, users need to configure language preferences.
To configure language preferences in Internet Explorer:
From the Tools menu, select Internet Options.
The Internet Options window appears.
Click Languages.
The Language Preference window appears.
The language you plan to use must display at the top of the list to have priority.
If the language you plan to use is listed:
Select the language.
Click Move Up to move the language you plan to use to the top of the list.
If the language you plan to use is not listed:
Click Add.
The Add Language window appears.
Select a language.
Click OK.
The Language Preference window returns.
Select the language you have added, and click Move Up to move it to the top of the list.
Click OK.
A locale ID is a standardized ID that represents a language and region in which the language is spoken. For example, fr-CA is the locale ID for French spoken in Canada, and es-MX is the locale ID for Spanish spoken in Mexico.
Localizing UIM involves copying and renaming existing files to include a locale ID. The renamed files that include a locale ID become the translated version of the original files.
To determine the locale ID in Internet Explorer:
From Tools menu, then select Internet Options.
The Internet Options window appears.
Click Languages.
The Language Preference window appears.
Click Add.
The Add Language window appears.
Languages are listed alphabetically. Several languages are spoken in more than one country, so the locale ID reflects the language and the country in which the language is spoken.
Locate the language to which you are localizing and note the locale ID.
Close the Add Language, Language Preference, and Internet Option windows.
Localizing the UIM UI involves working with a UIM-provided cartridge that you import into Oracle Communications Design Studio, modify, and deploy. Design Studio also provides various editors, such as an XML editor and an HTML editor, that you can use to translate files for localization.
The following sections describe localizing UIM:
The UI-specific files are a set of .xlf and .properties files that contain localizable text strings that define labels and messages. You modify the text string within these files to localize UIM.
.xlf files
The UIM UI was written using Application Development Framework (ADF). ADF-specific files use the .xlf file extension. XLF files contain localizable text strings for labels that display in the UI.
.properties files
The UIM UI calls UIM API methods, which may result in an information, warning, or error message displaying in the UI. Properties files contain localizable text strings for API messages that display in the UI.
Localizing the UI is accomplished by modifying the text strings in XLF and properties files that display in the UI.
To localize the UI-specific files, perform the work described in the following sections:
Note:
Within Design Studio, you must be in the Studio Design perspective Studio Projects view.
Within Design Studio, you must be in the Studio Design perspective Cartridge view.
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.
Note:
Within Design Studio, you must be in the Java perspective Package Explorer view.
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 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:
Right-click on the file and select Copy.
Right-click on the parent directory of the copied file and select Paste.
The Name Conflict dialog box appears.
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.
Click OK.
Note:
If you copy and paste the file, and then try to rename it, the Rename menu option is not available when right-clicking on the file in the Java perspective. You can, however, copy and paste the file and rename by selecting File from the menu, and then selecting Rename.
To edit the UI-specific files, perform the work described in the following sections:
Editing the XLF Files
To edit the XLF files within Design Studio:
Open the Java perspective.
Open the Package Explorer view.
Within the imported project, locate the XLF files.
See "Locating the UI-Specific Files within the Project" for more information.
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.
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.
Note:
The Preferences.xlf file defines a date format. If you want to localize the date format, see "XLF Files" for more information.
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>
Editing the Properties Files
To edit the properties files within Design Studio:
Open the Java perspective.
Open the Package Explorer view.
Within the imported project, locate the properties files.
See "Locating the UI-Specific Files within the Project" for more information.
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.
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.
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
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.
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-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.
Example 12-3 Languages with Use of Single Quotes Need Two Single Quotes
status.PENDING_ASSIGN=En attente d''attribution
Example 12-4 system.properties Entry with a Date Format
system.dateFormat=MM/dd/yyyy
Example 12-5 system.properties Entry with a Modified Date Format
system.dateFormat=dd/MM/yyyy
Localized files are modified as part of a project. After the modifications are complete, build the project to create the cartridge that can be deployed into UIM. Every cartridge should be cleaned and rebuilt prior to deploying.
See UIM Cartridge Guide for information about deploying cartridges and cartridge packs.
Note:
When a cartridge containing localizable XLF files is deployed into UIM, the inventory.ear file is automatically redeployed, resulting in the localization changes being applied to the UI.
The following sections describe localizing UIM Help:
The UIM Help uses Oracle Help for the Web. Oracle Help is a browser-based Help system that runs as a Web application based on a Java servlet. You do not need specialized knowledge of Oracle Help to localize UIM Help; you can use the information in this chapter, supplemented by the Oracle Help documentation. See Oracle Fusion Middleware Developing Help Systems with Oracle Help for more information:
http://docs.oracle.com/middleware/1213/jdev/develop-help/toc.htm
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.
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.)
To localize UIM Help, perform the work described in the following sections:
Use the default Help files installed with UIM as the starting point for your localization.
To extract the Help files:
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.
Open the tempDir/uimoh_help.jar file.
Extract all the objects in the uimoh_help.jar file into tempDir.
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
To translate the Help files, perform the work described in the following sections:
Translating the Copyright Page
To translate the copyright page:
Navigate to the tempDir/dcommon/html directory.
Open the cpyr.htm file.
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 © 1994-2012, Oracle and/or its affiliates. All rights reserved.</p>
Translating the Help Topics
To translate the Help topics:
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.
Open an .htm file.
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.
Repeat steps 2 and 3 for each .htm file in the tempDir directory.
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>
Translating the Table of Contents
To translate the Table of Contents:
Navigate to the tempDir directory.
Open the toc.xml file.
Each item in the Table of Contents is defined by a <tocItem> element.
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">
Note:
Oracle Help automatically translates the Help window menu options; field names; and informational, warning, and error messages. The translation is based on the locale defined in the ohwconfig.xml file.
For example, if the only language preference specified is English, and the ohwconfig.xml file defines a single locale of French, Oracle Help translates the Help window menu options, field names, and messages to French.
Oracle recommends that the language preference with the highest priority be the same language defined as the locale in the ohwconfig.xml 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.
Note:
Using Oracle Help Indexer requires that you have Java installed.
To install Oracle Help Indexer:
Go to the Oracle Technology Network website:
http://www.oracle.com/technetwork/topics/utilsoft-085729.html
Download the help-indexer.jar file to tempDir, where tempDir is a local directory.
To regenerate the search index file using Oracle Help Indexer:
Open a Windows command prompt.
Change the directory to tempDir by entering the following command:
cd tempDir
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
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:
Navigate to the tempDir directory.
The tempDir directory contains the uimoh_help.jar file, the translated Help files, and the regenerated search index file.
Copy the uimoh_help.jar file to tempDir to create a second copy of the uimoh_help.jar file in tempDir.
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.
Open the uimoh_help_locale.jar file.
Delete all of the objects in the JAR file.
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.
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.
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:
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>
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
The default Help system is deployed when you deploy the inventory.ear file.
To deploy the localized Help system:
Repackage the UIM_Home/app/inventory.ear file to include the localized Help files by doing the following:
Delete the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help/helpsets/uimoh_help.jar file.
Copy the tempDir/uimoh_help_locale.jar file to the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help/helpsets directory.
Note:
If your UIM Help is supporting multiple locales, each JAR file defined by each <locale> element in the ohwconfig.xml file must be present in the UIM_Home/app/inventory.ear/inv.war/WEB-INF/help/helpsets directory.
Deploy the repackaged inventory.ear file.
For instructions on how to deploy the inventory.ear file, see UIM System Administrator's Guide.
After you deploy the localized Help system, test your UIM environment to verify that the localized Help system is working correctly.
In UIM, open the Help and do the following:
Navigate to several topics from links in the Table of Contents to ensure that the correct topics appear and display correctly.
Test several links within Help topics to ensure they are working.
Search for several terms and verify that you get the expected results.
If testing multiple locales that function as a single Help system, verify translations for all locales.
If testing multiple locales that function as separate Help systems, change the language preference priority to verify translations for each locale.