Translating Personalizations

This chapter covers the following topics:

Overview

OA Framework allows you to personalize HTML pages so you can tailor the Oracle E-Business Suite to better fit your organizational needs. Using the Personalization user interface, you can modify the text on a page by either changing the prompt for an item or by adding new items to a page. You can then translate this text, into any installed languages at your site. Translation of personalized text is available only at the administrative level and not at the end-user level. End user personalizations are maintained in the selected user session language.

To translate your personalizations and manage your translations inline in the OA Personalization Framework UI, use the Manage Personalization Levels page of the Administrative-Level Personalizations UI.

To perform bulk translations of your personalizations, you can use the set of command line translation tools, following the steps outlined in this document for Translating Personalizations Stored in MDS.

Translating Personalizations Stored in MDS

If you personalize pages that reside in the MDS Repository, you can perform bulk translations of the personalizations using the following steps, which employ the OA Extension Translation toolset:

  1. You must initially create MDS Personalizations in the base language of your Oracle E-Business Suite installation before you can translate the text portion of the personalizations to other languages. System Administrators who create the personalizations should first set their Language Preference to the base language specified in FND_LANGUAGES.

  2. Go to the APPL_TOP directory and source the file APPSORA.env to set all your environment variables. For Windows, refer to the Oracle E-Business Suite Maintenance Procedures to display an appropriate command prompt window and use the resulting command prompt window to set your environment variables (run %APPL_TOP%\envshell.cmd).

  3. Determine the location of the personalization document to translate. You can determine the path of the MDS personalization document you wish to export/extract by using the following rules:

    • Note the original path to the document you personalized. This is found in the Personalization Context section of the Personalize page (for example: Document Name: /oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG).

    • Add '/customizations/', the personalization level, and level value that you have chosen in the personalization UI to the path of the document following the 'webui' directory, but before the component name in the document reference path. The personalization levels and level values are defined in the following table:

      Level Level Value
      Function Function Code
      Site 0 (zero)
      Organization Organization ID
      Responsibility Responsibility ID
      User User ID

      These values combined with the original document reference form the path to the customization document stored in the MDS repository.

      Example 1

      The Notification Worklist Table has a base document path of: /oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG.

      If you created a site level personalization for this document your resulting path to the customization document would be: /oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG

      Example 2

      Suppose you create for the Notification Worklist Table, a function level personalization for the 'High Priority Worklist' custom function. In this case you need to know the function code for the 'High Priority Worklist' function. Let's assume it's OAFHP_WORKLIST. The path to the document would be: /oracle/apps/fnd/wf/worklist/webui/customizations/function/OAFHP_WORKLIST/AdvancWorklistRG

    You can also use SQL*Plus to review all the personalizations for a given base document. JDR_UTILS is a PL/SQL package that allows you to evaluate the list of personalization documents that are in your MDS repository. Included in this package is a procedure called jdr_utils.listcustomizations(''); which allows you to see the personalization document path names that are currently defined in MDS. To run this procedure, launch Sql*Plus, set serveroutput on, and execute the jdr_utils.listcustomizations(''); command. Replace the '' reference with an actual base document reference. For example, to see all the personalization documents for the Notifications Worklist Table, execute the following command:

    exec jdr_utils.listcustomizations('/oracle/apps/fnd/wf/
  worklist/webui/AdvancWorklistRG');

    If you run the example above, you may notice function personalization document references that you did not create. These are Oracle-seeded function-level personalizations created by the Oracle E-Business Suite development teams. Personalization definitions are seeded by development teams so that they can share components across products and vary their look and behavior slightly with each use.

    For more information about JDR_UTILS, refer to the Inspecting the MDS Repository Content section in the Testing and Debugging chapter of the Oracle Application Framework Developer's Guide.

  4. Determine the list of required translations by using the following SELECT statement:

    select language_code, nls_language from fnd_languages 
  where installed_flag in ('I', 'B');

    For every language retrieved that needs translations, you will need to specify that language for the -languages option when you run the XLIFF Extractor in the next step. Specify the languages for the -languages option as the language-territory code using the format xx-YY, where xx is the two character language code, in lower case, and YY is the two character territory code in upper case.

    Note: If the last two characters of the language-territory code are not in upper case, the XLIFF Importer automatically converts them to upper case and logs a warning.

    The following mapping was used when migrating translations from AK format to OA Extension format, to map the Oracle E-Business Suite language code to the xx-YY format.

  5. Use the XLIFF Extractor tool directly against the MDS DB repository to export and extract the base language personalized content into an XLIFF file (.xlf) in one step. (Note that earlier versions of the XLIFF Extractor were only able to extract language content from .xml files and as a result, you had to first export the personalizations into .xml files using the Export tool, then use the XLIFF Extractor tool to extract the base language content from the Xml to an XLIFF file.)

    The XLIFF formatted file contains information regarding the translatable personalization properties and is the document that you physically translate into your installed languages. You can send out large volumes of translation content to a 3rd party translator, if necessary, using this mechanism.

    Insert into the path of the original document you personalized, the personalization level and level value mapping information determined in Step 3 to derive the fullPathOfFileName_or_directoryname for the following command:

    Java oracle.jrad.tools.trans.extractor.XLIFFExtractor <fullPathOfFileName_or_directoryname>
   -username <MDS repository username>
   -password <MDS repository password>
   -dbconnection <database connection string in TNSNAMES format>
   -root <root directory, where all the MDS documents (Xml files) can be found or be saved to>
   -source db
   -languages <List of comma separated target languages 
   for which the XLIFF documents are to be created.>
   -mmd_dir <directory location of the MMD files to use>
   -xliff_dir <source directory for XLIFF files. This is where your XLIFF files 
   will be created or expected by the XLIFF Importer.>

    Example

    The following example first exports the base language site level personalizations of the Advanced Worklist table document /oracle/apps/fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG and saves the content to a Xml document in the root directory $APPL_TOP/admin/patch. It then extracts the translatable information from the Xml document and saves it to two .xlf files with the target language set for each file as "fr-FR" or "ja-JP". The two .xlf files are saved under two new subdirectories named for the respective languages specified, beneath the directory specified by the -xliff_dir option.

    Note: You can place the documents under any root directory you wish using the -root parameter. These examples use $APPL_TOP/admin/patch for convenience.

    Java oracle.jrad.tools.trans.extractor.XLIFFExtractor /oracle/apps/
  fnd/wf/worklist/webui/customizations/site/0/AdvancWorklistRG 
  -rootdir $APPL_TOP/admin/patch -username APPSNAME 
  -password APPSPWD -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
  (HOST=yourhost)(PORT=yourport))(CONNECT_DATA=(SID=yoursid)))"
  -source db -languages Fr-FR,ja-JP -mmd_dir $OA_HTML/jrad 
  -xliff_dir $APPL_TOP/admin/patch/oracle/apps/fnd/wf/
    worklist/webui/customizations/site/0/

    The preceding example exports and extracts the translatable information for

    /oracle/apps/fnd/wf/worklist/webui/
  customizations/site/0/AdvancWorklistRG

    to

    $APPL_TOP/admin/patch/oracle/apps/fnd/wf/worklist/webui/
  customizations/site/0/Fr-FR/AdvancWorklistRG.xlf


$APPL_TOP/admin/patch/oracle/apps/fnd/wf/worklist/webui/
  customizations/site/0/JA-JP/AdvancWorklistRG.xlf

    Note: The XLIFF files should be UTF-8 encoded so that the translated strings are imported correctly and subsequently used correctly during runtime.

  6. From this point on, the copies of the base XLIFF files are referred to as the language XLIFF files and you will be updating these language XLIFF files with the appropriate language translations.

    An Example Language XLIFF File

    <?xml version = '1.0' encoding = 'UTF-8'?> 
<xliff version="1.0"> 
  <file datatype="jdr" original="PayTermsLOVRN" 
    product-version="$Header: PayTermsLOVRN.xlf 115.1 
    2003/02/26 19:58:26 jfrost noship $" source-language=
    "en-US" target-language="Fr-FR" product-name="qp"> 
      <body> 
         <trans-unit id=".oracle.apps.qp.lov.webui.
           PayTermsLOVRN..PTName...prompt" translate="yes" 
           maxbytes="4000" maxwidth="26" size-unit="char"> 
            <source>Payment Terms</source> 
            <target>Payment Terms</target> 
            <prop-group name="ora_untranslatable"> 
               <prop prop-type="tagName">messageStyledText
                 </prop> 
               <prop prop-type="attributeName">prompt</prop> 
            </prop-group> 
         </trans-unit> 
         <trans-unit id=".oracle.apps.qp.lov.webui.
           PayTermsLOVRN..TermId...prompt" translate="yes" 
           maxbytes="4000" maxwidth="14" size-unit="char"> 
            <source>Term Id</source> 
            <target>Term Id</target> 
            <prop-group name="ora_untranslatable"> 
               <prop prop-type="tagName">formValue</prop> 
               <prop prop-type="attributeName">prompt</prop> 
            </prop-group> 
         </trans-unit> 
      </body> 
   </file> 
</xliff>

  7. For each language XLIFF file, there is a <trans-unit> element in the XLIFF file for every translatable component extracted from the XML file. The <source> element in each <trans-unit> contains the translatable string specified in the source language. The <target> element represents the same string translated to the target language. Update the string in the <target> element for each <trans-unit> element you want to translate.

  8. Once you complete the translation of each language XLIFF file, use the XLIFF Importer to import the translations into the MDS repository.

    Example

    The following example imports the translated XLIFF file

     $APPL_TOP/admin/patch/oracle/apps/fnd/wf/worklist/webui/
   customizations/site/0/Fr-FR/AdvancWorklistRG.xlf

    to the MDS repository:

    Java oracle.jrad.tools.trans.imp.XLIFFImporter 
  -username APPSNAME 
  -password APPSPWD 
  -dbconnection "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
    (HOST=yourserver)(PORT=yourport))(CONNECT_DATA=
    (SID=yoursid)))"
  $APPL_TOP/admin/patch/oracle/apps/fnd/wf/worklist/webui/
    customizations/site/0/Fr-FR/AdvancWorklistRG.xlf

OA Extension Translation Toolset

The OA Extension Translation toolset deals with translatable information contained in OA Extension pages using XLIFF, a widely used XML format for transferring and manipulating translatable resources.

Note: The toolset actually uses oraXLIFF, an Oracle dialect of XLIFF defined and used by WPTG (Oracle's Worldwide Product Translation Group).

The Translation toolset consists of the following:

XLIFF Extractor

The XLIFF Extractor extracts the translatable information from a given OA Extension document, into an oraXLIFF file. The XLIFF Extractor can:

The XLIFF Extractor for the Oracle E-Business Suite behaves according to the following rules:

Oracle E-Business Suite-Specific Rules

General Rules

Important: If the value of xml:lang is 'end-US', apply only Oracle E-Business Suite-specific rules 2 and 3 and general rule 2.

To use the XLIFF Extractor, ensure that your classpath, path and environment are set up similar to the environment required for applying an AD patch, and call Java oracle.jrad.tools.trans.extractor.XLIFFExtractor <full_path_of_file_or_directory_name> with the appropriate parameters.

If you have Oracle JDeveloper OA Extension, you may alternatively use the xliffextract.bat script for Windows or the xliffextract shell script for Linux that is packaged with the JDeveloper IDE, located in the jdevbin\jdev\bin directory of the JDeveloper install area. The batch file and shell script each set up the classpath, path and environment for you. Just typing xliffextract for Windows or ./xliffextract for Linux at the command prompt without any parameters will give help about its usage. Parameters enclosed in square brackets [ ] are optional.

Example

Java oracle.jrad.tools.trans.extractor.XLIFFExtractor 
  <fullPathOfFileName_or_directoryname> 
[-username <username>]
[-password <password>]
[-dbconnection <database_connection>]
[-xliff_extension <xliff_extension>]
[-root <MDS_root_dir>]
-mmd_dir <dir_of_MMD_files>
[-DBDRV <APPS_db_drivers>]
[-xliff_dir <XLIFF_output_dir>]
[-rootPackage <rootpkg>]
[-includeSubpackages]
[-product_name <product_name>]
[-category <category>]
[-source (db | file)]
[-languages <target_language(s)>]

Note: In addition to the parameter passing style shown above, you may also pass parameters using the style, parameter=<value>.

Replace the arguments as indicated in the explanation of the parameters below:

Using XLIFF Extractor with the -languages parameter

If both the XML file from the file system and the XML file from repository are different (XML file from file system contains extra translatable strings), you can use XLIFF Extractor with the -languages option. This merges the translated attributes from the repository so that the generated XLIFF file contains both translated and untranslated strings.

XLIFF Extractor does the following when the -languages option is specified:

Attribute "AAA" in XML in file system Translation for attribute "AAA" in repository XLIFF file
Not present Present Attribute string ignored.
Present Not present Contains untranslated "<target>AAA<target>"
Present Present, translation string is BBB Contains "<target>BBB<target>"

Using the Export tool with -translation option

If both the XML file from the file system and the XML file from the repository are the same, you can use Export -translations to export and extract the XLIFF file. The resulting XLIFF file contains only the translated strings. You can use this method to transfer the already translated contents from your repository to the file system, so you can then move the translations from one repository to another. Note that in the degenerate case where translations for all the translatable attributes of a XML file exist in a repository, the XLIFF files created by both "Export -translations" and "xliffExtract -languages" are similar.

Notes:

XLIFF Extractor Examples

To extract the base language content from the FND_MESSAGES_PAGE.xml file in the file system into a new document located in f:\temp\oracle\apps\fnd\pages\US\FND_MESSAGES_PAGE.xlf (for Windows) or /private/oaext/oracle/apps/fnd/pages/US/FND_MESSAGES_PAGE.xlf (for Linux):

To extract the base language content from the personalized FND_MESSAGES_PAGE.xml file in the file system into a new document located in f:\temp\oracle\apps\fnd\pages\US\FND_MESSAGES_PAGE.xlf (for Windows) or /private/oaext/oracle/apps/fnd/pages/US/FND_MESSAGES_PAGE.xlf (for Linux):

To extract translation content for XML from a repository:

When you extract translation content for XML with different target languages, XLIFF Extractor creates multiple copies of the XLIFF file, one for each language. Each copy is saved to the same directory structure, under a subdirectory of the same name as the target language. The following Windows example creates the files c:\temp\Fr-FR\page1.xlf with target-language="Fr-FR" and c:\temp\JA-JP\page1.xlf with target-language="JA-JP".

XLIFF Importer

The XLIFF Importer takes a translated XLIFF file and imports it into the MDS Repository. This effectively deploys the translated OA Extension document. The Importer tool performs the following validations on the XLIFF files it imports:

To use the XLIFF Importer, ensure your classpath, path and environment are set up similar to what is required for applying an AD patch and call Java oracle.jrad.tools.trans.imp.XLIFFImporter <full_path_of_file> with the appropriate parameters.

If you have Oracle JDeveloper OA Extension, you may alternatively use the Windows xliffimport.bat file or the xliffimport Linux shell script that is packaged with the JDeveloper IDE, located in the jdevbin\jdev\bin directory of the JDeveloper install area. The batch file and shell script each set up the classpath, path and environment for you. Just typing xliffimport without any parameters will give help about its usage.

Java oracle.jrad.tools.trans.imp.XLIFFImporter 
  <full_path_of_file>
-username <username>
-password <password>
-dbconnection <database>

The arguments should be replaced as described for the corresponding parameters below:

Mapping a Language Code to a Language-Territory Code

The following list identifies the language code to language-territory code mapping used when migrating translations from AK format to OA Extension format:

US = en-US
AR = ar-AE
AS = as-IN
BN = bn-IN
PTB = pt-BR
BG = bg-BG
FRC = fr-CA
CA = ca-ES
HR = hr-HR
CS = cs-CZ
DK = da-DK
NL = nl-NL
EG = ar-EG
GB = en-GB
ET = et-EE
SF = fi-FI
F = Fr-FR
D = de-DE
EL = el-GR
GU = gu-IN
IW = he-IL
HI = hi-IN
HU = hu-HU
IS = is-IS
IN = in-ID
I = it-IT
JA = JA-JP
KN = kn-IN
KO = ko-KR
ESA = es-US
LV = lv-LV
LT = lt-LT
MS = ms-MY
ML = ml-IN
MR = mr-IN
ESM = es-MX
N = no-NO
OR = or-IN
PL = pl-PL
PT = pt-PT
PA = pa-IN
RO = ro-RO
RU = ru-RU
ZHS = zh-CN
SK = sk-SK
SL = sl-SI
E = es-ES
S = sv-SE
TA = ta-IN
TE = te-IN
TH = th-TH
ZHT = zh-TW
TR = tr-TR
UK = uk-UA
VN = vi-VN

Known Issues

See a summary of key Personalization Translation issues with suggested workarounds if available.

Related Information