This chapter provides information on localizing the Oracle Communications Network Integrity UI and 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 Network Integrity UI and Network Integrity Help are written in English. If your company is based in France and you purchase Network Integrity, you may want to localize Network Integrity to display the UI and Help in French.
Localizing Network Integrity involves modifying a specific set of files that Network Integrity uses to display text in the UI and in the Help.
This chapter contains the following sections:
Note:
The procedures in this chapter use Windows syntax for directory paths and commands. If you are working on a Unix or Linux platform, adapt the syntax accordingly.Note:
Before localizing your Network Integrity environment, you must identify a strategy for maintaining future localizations. Oracle does not provide a delta file in which you can readily see the details of what changed between releases.The following software is required to localize Network Integrity:
Localizing the Network Integrity UI involves working with the Network Integrity localization pack that you import into Oracle Communications Design Studio, modify, and deploy into Network Integrity. Design Studio also provides various editors, such as an XML editor and an HTML editor, that you can use to translate files for localization.
Localizing the Network Integrity Help involves regenerating a search index file based on translated HTML files. This is accomplished using Oracle Help Indexer.
To access Help Indexer, download the help-indexer.jar file from the following website to a local directory such as tempDir:
http://www.oracle.com/technetwork/topics/utilsoft-085729.html
Using Help Indexer requires that you have Java installed. The java command should be in your path.
For a localized version of Network Integrity 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 Preferences 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 or Move Down to place the language you plan to use at 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 Network Integrity 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:
From Internet Explorer, select Tools, then select Internet Options.
The Internet Options window appears.
Click Languages.
The Languages window appears.
Click Add.
The Add Language window appears.
Languages are listed alphabetically. Several languages are spoken in more than just one country, so the locale ID reflects the language and the country in which the language is spoken. For example, there multiple locale IDs for French:
fr-BE for French spoken in Belgium
fr-CA for French spoken in Canada
fr-FR for French spoken in France
fr-LU for French spoken in Luxembourg
fr-MC for French spoken in Monaco
fr-CH for French spoken in Switzerland
Locate the language to which you are localizing and determine the appropriate locale ID.
Close the Add Language, Languages, and Internet Option windows.
The following sections describe localizing Network Integrity:
The Network Integrity UI makes use of the full depth of i18n support provided by the Application Development Framework (ADF) stack. The application UI is fully internationalized by making use of XML Localization Interchange File Format (XLF) files to keep all display strings separate from other code artifacts. Various parts of the ADF stack (ADF Faces, ADF Model, and ADF Data Control) are also built with full i18n support. A localization pack is a collection of XLF files and other property files, that together localize the UI to another language. A localization pack can be built into a cartridge that can be deployed into Network Integrity.
The expected outcome is that the user can successfully create, build, and deploy a localization pack.
Use the following procedure to create a localization pack:
Download localization.iar from the localization pack in the Oracle Communications Network Integrity 7.3.2 Software Developer Kit (included with the Oracle Communications Network Integrity 7.3.2 software) on the Oracle software delivery website:
Note:
The localization pack also contains a partial sample traditional Chinese localization, for your reference, where parts of the Scan Configuration Creation page are translated into traditional Chinese.Extract the META-INF/MANIFEST.MF file to a temporary location.
Open MANIFEST.MF and edit the value of Bundle-Name: Localization and Bundle-Description: Localization as follows:
Bundle-Name: Localization : localization_pack_name Bundle-Description: Localization : localization pack description
Where localization_pack_name is the name of the localization pack you are creating, and where localization pack description describes the localization pack you are creating.
Save MANIFEST.MF and return it to localization.iar/META-INF.
Extract META-INF/cartridge.xml to a temporary location.
Open cartridge.xml and edit the values of the name and languageCode tags:
<localizations>
<localization>
<name>Locale_Name</name>
<languageCode>Locale_ID</languageCode>
</localization>
</localizations>
Where Locale_Name is the locale of the localization pack you are creating; for example, French, and where Locale_ID is the standardized locale 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. A locale ID can also represent a language without specifying the region in which the language is spoken. For example:
<localizations>
<localization>
<name>French</name>
<languageCode>fr</languageCode>
</localization>
</localizations>
Save cartridge.xml and return it to localization.iar/META-INF.
Extract localization.iar/localization.jar to a temporary location.
Extract localization.jar/oracle to a temporary location.
Edit all the XLF files found in localization.jar/oracle or any of its nested folders:
Edit the name of each XLF file to add an underscore and the locale ID before the file extension, as shown in the following example:
DisAddressMsgBundle_fr.xlf
Note:
Compound locale IDs, such as fr-CA, should be added to the XLF file name with an underscore in the place of the hyphen, as in the following example:DisAddressMsgBundle_fr_CA.xlf
Open each XLF file and edit the file tag so that the source-language attribute is set to the locale ID, as in the following example:
<file source-language="fr" original="oracle.communications.inventory.api.entity.PhysicalPortMsgBundle" datatype="xml">
Note:
The source-language attribute for compound locale IDs, such as fr-CA, should be set to the first two characters only, as in the following example:<file source-language="fr" original="oracle.communications.inventory.api.entity.PhysicalPortMsgBundle" datatype="xml">
Open each XLF file, locate each trans-unit tag and edit its child source tag with the translated value for the desired localization.
Edit all the PROPERTIES files found in localization.jar/oracle or any of its nested folders:
Edit the name of each PROPERTIES file to add an underscore and the locale ID before the file extension, as shown in the following example:
IntegrityUIBundle_fr.properties
Note:
Compound locale IDs, such as fr-CA, should be added to the XLF file name with an underscore in the place of the hyphen, as in the following example:IntegrityUIBundle_fr_CA.properties
Open each PROPERTIES file and edit the value for each key with the translated value for the desired localization. For example, edit the INTEGRITY_MANAGE_SCAN_CONFIG key, as in the following example:
INTEGRITY_MANAGE_SCAN_CONFIG=new_value
Where new_value is the translated value for the key for the desired localization.
(Optional) To enter extended character values (such as Chinese characters), you must use Unicode Escapes (only one character is allowed per escape sequence). Save each PROPERTIES file with UTF-8 encoding, then convert each PROPERTIES file to Unicode Escapes using the native2ascii tool provided with your JDK by entering the following command:
native2ascii -encoding UTF-8 input_file_name output_file_name
Where input_file_name is the name of the PROPERTIES file being converted, and where output_file_name is the name of the converted file.
See the partial sample Chinese localization included in the localization pack for an example.
Return all XLF and PROPERTIES files to localization.jar.
Return localization.jar to localization.iar.
Deploy localization.iar using the cartridge deploy tool.
(Optional) To localize link names in the Link panel in the Network Integrity UI, you must edit the MBean with the translated values for the desired localization. See Network Integrity System Administrator's Guide for more information about viewing and editing the MBean.
(Optional) To localize cartridge-specific scan parameters, see the Design Studio Help. Cartridge-specific scan parameters can be localized within Design Studio, where you can set multiple language preferences and then assign a language preference to a scan parameter group.
After the translations are complete, build the localization pack to create a cartridge that can be deployed into Network Integrity. Every cartridge should be cleaned and rebuilt prior to deploying.
See the Design Studio Help and the Network Integrity Installation Guide for more information about deploying cartridges.
Note:
When a cartridge containing localizable XLF files is deployed into Network Integrity, the NetworkIntegrity.ear file automatically redeploys, resulting in the localization changes being applied to the UI.When running the Network Integrity UI, the user chooses the appropriate language from the web browser. This is usually done using the Character or Text Encoding menu of the browser, or from a Language preference setting. The UI displays the selected language after the corresponding localization pack is deployed. Otherwise, the UI displays the default English language.
There may be parts of the UI that are supplied by third parties, which are not fully internationalized. Those parts always display in English.
The following sections describe localizing Network Integrity Help:
Network Integrity 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 Network Integrity Help; you can use the information in this chapter, supplemented by the Oracle Help documentation. See Oracle Fusion Middleware Developer's Guide for Oracle Help for more information.
Network Integrity Help consists of a set of files, as described in the following sections.
This section provides information about the Help files, including their location, a brief description of their purpose, and whether or not they require configuring or translating for localization. For details about configuring or translating the content of the Help files, see "Localizing the Network Integrity Help Files".
An Oracle Help configuration file is located in the NI_Home/integrity/ NetworkIntegrity.ear/NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/ helpsets directory. The ohwconfig.xml configuration file contains references to each Help system deployed into an application. Upon installation, the ohwconfig.xml file references the default Network Integrity Help system (English) deployed into Network Integrity. This file requires configuration for localization.
The Network Integrity Help files are located in the NI_Home/integrity/ NetworkIntegrity.ear/NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/WEB-INF/lib/Network_Integrity_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.
Network_Integrity_Help.hs: This file describes the Help system. When Network Integrity Help is initiated through the Network Integrity UI, Network_Integrity_Help.hs is the starting point. This file does not require translation.
toc.xml: This file defines the Table of Contents (TOC) 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 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 "Software Requirements" and "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 Network Integrity Help, perform the work described in the following sections:
Use the default Help system installed with Network Integrity as the starting point for your localization.
To extract the Help files:
Copy the NI_Home/integrity/NetworkIntegrity.ear/NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/WEB-INF/lib/Network_Integrity_Help.jar file to a local directory, such as tempDir.
Open the tempDir/Network_Integrity_Help.jar file.
Select all objects in the Network_Integrity_Help.jar file and extract them into the same directory in which the Network_Integrity_Help.jar file resides (tempDir).
Click the File column heading in the tempDir directory to sort the objects by file type.
The following objects are present:
dcommmon directory
img directory
META-INF directory
target.db
Network_Integrity_Help.jar
Network_Integrity_Help.hs
numerous *.htm files
search.idx
map.xml
toc.xml
You do not need to do anything with the img or META-INF directories, or with the target.db, Network_Integrity_Help.hs, or map.xml files.
To translate the Help files, perform the translations described in the following sections:
Translating the Copyright Page
The copyright page text is defined in the tempDir/dcommon/html/cpyr.htm file. Translate the content of the title, heading, and paragraph elements (<title>, <h1> - <h6>, <p>) to the local language.
For example, translate the bolded content in Example 15-1:
Example 15-1 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>
The Help topics text is defined in the numerous tempDir/*.htm files, and each file requires translating.Translate the content of the title, heading, paragraph, and table data elements (<title>, <h1> - <h6>, <p>, <td>) to the local language.
For example, translate the bolded content in Example 15-2. Elements that are not text, such as the HTML tags themselves, should not be changed.
Example 15-2 Excerpt from olh_integ_scans002.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>Creating a Scan</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = ohj/ohw) - Version 5.1.2 Build 040" />
<meta name="date" content="2011-12-20T20:51:30Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Creating a Scan" />
<meta name="relnum" content="Release 7.1" />
<meta name="partnum" content="E23703-01" />
<meta name="topic-id" content="CreateScansMain" />
<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="CJAJAIGJ" name="CJAJAIGJ"></a><a id="CreateScansMain" name="CreateScansMain"></a></p>
<div class="sect2">
<h1>Creating a Scan</h1>
<p>To create a scan:</p>
<ol>
<li>
<p>From the Tasks panel, click <span class="bold">Manage Scans</span>.</p>
<p>The Manage Scans page appears.</p>
</li>
Translating the Table of Contents
The TOC text is defined in the tempDir/toc.xml file. Each item in the TOC is defined by a <tocItem> element. Translate the content to the local language.
For example, translate the bolded content of the text attribute in Example 15-3. Do not change the content of the target attribute.
Example 15-3 Excerpt from toc.xml
<tocitem target="olh_integ_main001.htm-sthref3" text="Getting Started with Network Integrity" />
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.
That said, 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.
To regenerate the search index file:
Download the help-indexer.jar file to a local directory, such as tempDir, and install Java.
See "Software Requirements" for more information.
Open a Windows command prompt.
Change the directory to the directory containing the translated Help files 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
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
In the above command:
java is the java command in your path. If it is not in your path, specify the full path to java.exe.
-mx64m increases the default heap size. This is optional, but the Oracle Help documentation recommends that you specify it.
-classpath specifies the location of the help-indexer.jar file.
oracle.help.tools.index.Indexer is the Java class that is called to regenerate the search index. This Java class file resides in the help-indexer.jar file.
-l specifies the locale, 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. If you do not specify a locale, the system's default locale is used.
See "Determining the Locale ID" for more information.
-e specifies the Java-supported character set encoding (charset). For example, 8859_1.
pathToHelpFiles is the full path to the translated Help files.
search.idx is the name of the search index file that Network Integrity Help uses.
See Oracle Fusion Middleware Developer's Guide for Oracle Help for more information about these parameters.
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:
In Windows Explorer, navigate to the tempDir directory. This is the directory containing the Network_Integrity_Help.jar file, the translated Help files, and the regenerated search index file.
Copy the Network_Integrity_Help.jar file, and paste it in the same directory (tempDir).
Select the copied version of the Network_Integrity_Help.jar file and rename it Network_Integrity_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".
Open the Network_Integrity_Help_locale.jar file.
Select and delete all of the objects in the JAR file.
Add the localized Help files to the Network_Integrity_Help_locale.jar file. (This includes all of the directories and all of the files in tempDir, with the exception of Network_Integrity_Help.jar and Network_Integrity_Help_locale.jar.
Save and close the Network_Integrity_Help_locale.jar file.
You can verify that you included all of the directories and files by checking the number of objects in the Network_Integrity_Help.jar file and in the Network_Integrity_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 NI_Home/integrity/NetworkIntegrity.ear/ NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/ helpsets/ohwconfig.xml file to reflect the localized Help JAR file.
To configure the ohwconfig.xml file:
Open the ohwconfig.xml file.
The file defines the default Help system (English):
<locales>
<!-- English: -->
<locale language="en">
<books>
<helpSet id="integrity"
jar="../WEB-INF/lib/Network_Integrity_Help.jar"
location="Network_Integrity_Help.hs"/>
</books>
</locale>
</locales>
Update the <locale> element to reflect the localized Help system:
<locales>
<!-- French Canadian: -->
<locale language="fr">
<books>
<helpSet id="integrity_fr_ca"
jar="../WEB-INF/lib/Network_Integrity_Help_fr_ca.jar"
location="Network_Integrity_Help.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.
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 Network Integrity upon redeployment:
<locales>
<!-- French: -->
<locale language="fr">
<books>
<helpSet id="integrity_fr_ca"
jar="../WEB-INF/lib/Network_Integrity_Help_fr_ca.jar"
location="Network_Integrity_Help.hs"/>
</books>
</locale>
</locales>
<locales>
<!-- Spanish: -->
<locale language="es">
<books>
<helpSet id="integrity_es_mx"
jar="../WEB-INF/lib/Network_Integrity_Help_es_mx.jar"
location="Network_Integrity_Help.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 Network Integrity 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 <combineBooks> to true. The Help navigational views behave as a single, integrated Help system.
To use separate Help systems, set <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 Network Integrity 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.
See Oracle Fusion Middleware Developer's Guide for Oracle Help for more information.
The original Help system, located in the NI_Home/integrity/NetworkIntegrity.ear/ NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/WEB-INF/lib/ Network_Integrity_Help.jar file, is deployed when you deploy the NetworkIntegrity.ear file.
To deploy the localized Help system:
Repackage the NI_Home/integrity/NetworkIntegrity.ear file to include the localized Help files. To do this:
Delete the NI_Home/integrity/NetworkIntegrity.ear/NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/WEB-INF/lib/Network_Integrity_Help.jar file.
Copy the tempDir/Network_Integrity_Help.jar_locale.jar file to the NI_Home/ integrity/NetworkIntegrity.ear/NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/WEB-INF/lib directory.
Note:
If your Network Integrity Help is supporting multiple locales, each JAR file defined by each <locale> element in the ohwconfig.xml file must be present in the NI_Home/integrity/NetworkIntegrity.ear/ NetworkIntegrityApp_NetworkIntegrityUI_webapp1.war/ WEB-INF/lib directory.Deploy the repackaged NetworkIntegrity.ear file.
For instructions on how to deploy the NetworkIntegrity.ear file, see Network Integrity System Administrator's Guide.
After you deploy the localized Help system, test your Network Integrity environment to verify that the localized Help system is working correctly.
In Network Integrity, open the Help. Tests should include 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.