Translating PeopleTools

This chapter provides an overview of PeopleTools translation, lists prerequisites, and discusses how to:

Use alternate language dynamic-link libraries (DLLs).
Locate resource directories.
Translate resource files.
Translate objects.

Understanding PeopleTools Translation

The PeopleSoft system provides utilities and methods for translating all definitional application objects built using PeopleTools, such as pages and reports. However, there are also some PeopleTools components that are visible to end-users and should be translated as well. These include messages issued by the Application Server, the Windows components of PeopleTools (such as the PS/nVision designer and PeopleSoft Query) and images used for standard navigation in the PeopleSoft Pure Internet Architecture.

This chapter explains the different translatable PeopleTools components, and how you can customize the translations delivered by PeopleSoft or translate PeopleTools into new languages.

Prerequisites

Before you begin modifying or creating new translations of PeopleTools, ensure that you have the required files and software tools.

This section discusses:

Required files.
Required tools.

To modify translations of PeopleTools or to translate PeopleTools into a new language, you must have installed the PeopleTools Language Development Kit. When you install PeopleTools, you have the option to install the PeopleTools Language Development Kit when you install the file server. If you have installed this kit, you will find a directory <PS_HOME>\SRC\RES on your file server. You can install the PeopleTools Language Development Kit at any time − if this directory does not exist on the file server where you are planning to perform the translation, rerun the PeopleTools setup program and select only this option.

PeopleSoft provides source code to the English language resource files and selected local language resources. PeopleSoft also supports header files that you need in order to produce your own alternate language DLLs. PeopleSoft also provides batch files to automate the resource compilation process.

In addition to the source code to the resource files that are delivered in the PeopleTools Language Development Kit, PeopleSoft also delivers pre-compiled alternate language DLLs for each language provided by PeopleSoft. These are installed by selecting the PeopleTools Language Pack from the PeopleTools installer. If you intend on using a translation that PeopleSoft provides but don’t plan on modifying PeopleTools translations, you only need to install the language pack, not the Language Development Kit.

The tools that you need to customize Windows resources are part of Microsoft’s Visual C++ compiler package. You won’t have to change or compile any C++ code, but you must use the resource compiler and linker. If you are translating any resources other than strings, you must use the Microsoft Developer Studio.

See Also

PeopleTools 8.46 PeopleBook: Hardware and Software Requirements Guide

Using Alternate Language DLLs

Although the vast majority of PeopleTools user interface elements viewed by the end user are stored in the database, PeopleTools executable modules do contain some translatable elements. When running PeopleTools components (such as the application server, PS/nVision and PeopleSoft Query) on Microsoft Windows, the translations are read from alternate language DLLs. An alternate language DLL is a file that stores translated strings for an associated PeopleTools DLL or EXE file (module). At runtime, the system uses the resources in the alternate language DLLs that correspond to the user’s language preference.

The PeopleSoft system uses a naming convention that includes the name of the base executable (the executable with which the alternate language DLL is associated) and the language code that identifies the language of the alternate language DLL. An alternate language DLL is named as follows:

PSZZZXXX.DLL

ZZZ	Three-character code that identifies the PeopleTools module associated with the alternate language DLL.
XXX	Three-character code that identifies the language of the alternate language DLL.

The alternate language DLL is used only to store translated resources. All code is executed from the base-language executable. The following diagram illustrates the structure of a base-language module (PSFOO.DLL) and its French alternate language DLL (PSFOOFRA.DLL):

Base language DLL and alternate language DLL

The system uses the resources that are stored in the alternate language DLL that matches the user’s language preference, if the DLL exists. Otherwise, it uses the resources that are stored in the base executable file.

Locating Resource Directories

Alternate language DLLs must be present on all application servers. Windows clients in a three-tier installation also must have the alternate language DLLs present.

Microsoft Windows NT application servers and Microsoft Windows client machines use Microsoft Windows resources from the base language and alternate language DLLs. UNIX/Linux application servers, however, store resources for all languages and modules in a single file, PSAPPSERV.RES. This file contains the same resources as the alternate language DLLs.

The following table shows the content of the directories that are used to support translated resources. These directories are distributed with PeopleTools and contain user-customizable resource files and other supporting files that are needed to compile, bind, name, and copy alternate language resource DLLs.

Directories and Files	Purpose
\SRC\RES	The root directory for alternate language resource DLLs. The files in this directory include some batch files that are used in constructing alternate language DLLs.
\SRC\RES\ENG	A prototypical alternate language development directory for the English language. There is one of these directories for each alternate language. Copy this directory for each new alternate language that you create.
\SRC\RES\ENG\INC	Holds header (.H) files that are common to several DLLs and various icons and bitmaps.
\SRC\RES\ENG\xxxxx	Within this directory, there is a directory for most PeopleTools DLL and EXE files found in \SRC\BIN. These directories contain the following file types: .RCX: string table resource files. .RC: menu and dialog box resource files. .CUR: cursors. .H: header files containing resource identifiers. .BMP: bitmap files used for icons and other graphical components. .ICO: icon files for Windows Explorer.

Translating Resource Files

To translate resource files into a new language, copy the source code for the English translations provided by PeopleSoft and use this as a starting point for the new language. Alternatively, if you are only making minor modifications to an existing translation provided by PeopleSoft (such as to change terminology), you can use any of the languages provided by PeopleSoft as a starting point. This section assumes that you are using the English translations as your start, and that you’re adding a new translation.

Note. PeopleSoft provides pre-translated PeopleTools alternate language DLLs for many languages, including French, Spanish, Dutch, Portuguese, Japanese, German, Italian, Danish, Polish, Swedish, Traditional Chinese, Simplified Chinese, Korean, and Canadian French. You must follow these steps only if you want to translate PeopleTools into a language that is not provided by PeopleSoft or if you want to modify one of the provided translations.

This section discusses how to:

Translate resource files.
Compile translated resource files using MAKEALTL.BAT (Windows).
Compile translated resource files using MAKEUNIX.BAT (UNIX/Linux).

Translating Resource Files

To translate resource files:

Determine the three-letter designation of the new language.

In this example, QUE is the designation for Quechua. For consistency in referring to languages throughout the system, use one of the standard code values stored in the Translate table for the LANGUAGE_CD field. The PeopleSoft system does not use standard ISO codes for languages, but three-letter codes instead. You can decide the appropriate three-letter code for your language, but you should ensure that it is consistently used across PeopleTools whenever you use this language.

See Adding New Languages.
Copy the contents of \SRC\RES\ENG to the target resource directory.

For Quechua, the target resource directory is \SRC\RES\QUE.
Use Microsoft Developer Studio to convert the English resources to the alternate language.

A text editor is adequate to change string resources contained in the *.RCX files, however when modifying *.RC files that contain Windows dialog boxes and other graphical elements, you should use the resource editor provided in Microsoft Developer Studio bundled with Microsoft Visual C++. The resource editor enables you to size and position elements in dialog boxes, edit bitmaps, cursors and other graphic components of the resource files.
Set up the environment variables.

Before compiling your translated resource files, you must set the appropriate environment variables for the C++ resource compiler. Typically, Microsoft Visual C++ provides a batch file, VCVARS32.BAT, which sets the variables for you. In addition to the variables set in this batch file, set the environment variable TOOLBIN to the <PS_HOME>\BIN\CLIENT\WINX86 directory of your file server, and append the <PS_HOME>\SRC\RES\ENG\INC directory to the environment variable INCLUDE.
Compile alternate language DLLs using MAKEALTL.BAT.
(Microsoft Windows NT application servers only) Copy the resultant alternate language DLLs to the BIN\SERVER\WINX86 directory of your Windows NT application server.
(UNIX/Linux application servers only) Compile UNIX/Linux application server resources and transfer to the UNIX/Linux application server.

If you are using a UNIX/Linux application server, you must run MAKEUNIX.BAT to compile the resource files into a format that is readable by the UNIX/Linux application server.

Note. If you have changed any menu item text, update the Security settings to give users access to the menu items.

The MAKEALTL.BAT file calls the Microsoft Visual C++ Resource Compiler and Linker to compile translated resources into a Windows DLL. Before running MAKEALTL.BAT, ensure that the environment variables required by the Resource Compiler and Linker are set correctly in your current DOS window. These environment variables are as follows:

Environment Variable	Description	Example
%path%	Must include your Microsoft Visual C++ executables directory.	C:\MSDEV\BIN
%include%	Must include your Microsoft Visual C++ INC directory and the Microsoft Foundation Classes (MFC) BIN directory. It must also include a copy of the PeopleTools resource include directory.	C:\MSDEV\INC C:\MSDEV\MFC\INC C:\PT810\SRC\RES\ENG\INC
%lib%	Must include your Microsoft Visual C++ library directory.	C:\MSDEV\LIB
%toolbin%	Must point to the directory containing your PeopleTools executables.	C:\PT810\BIN\CLIENT\WINX86

Once you have verified that the variables in the table above are correct, you can run MAKEALTL.BAT.

To run MAKEALTL.BAT:

In a DOS window, go to the SRC\RES directory.
Run the MAKEALTL batch file with <language> and <PeopleTools module> parameters.

This process compiles the resources into language-specific DLLs and copies the files to your PeopleTools executables directory.

The syntax of the command is as follows:
```
MAKEALTL <language> <PeopleTools module>
```

<language> is the three-letter code for the language that you are compiling (such as QUE).
<PeopleTools module> is the name of the directory that contains the resource files that you have translated (such as PSSYS).

Pass ALL in place of the directory name to compile all PeopleTools modules in the language that you specified.

Compile Translated Resource Files Using MAKEUNIX.BAT

MAKEUNIX.BAT compiles the translated resources into a single file that is readable by the PeopleSoft UNIX/Linux application servers. It reads the same translated resources as MAKEALTL.BAT, but instead of producing a separate DLL for each language/module combination, MAKEUNIX.BAT produces a single indexed resource file called PSAPPSRV.RES.

To run MAKEUNIX.BAT, you must also have the Microsoft Visual C++ development environment installed on your workstation. MAKEUNIX.BAT calls the C++ compiler to parse the resource files from all languages and to create PSAPPSRV.RES. In addition to the environment variables that are required to run MAKEALTL.BAT, MAKEUNIX.BAT requires that you set the %PSVER% environment variable. Set this variable to the base directory in which you installed PeopleTools.

If you have added any new languages as part of your PeopleTools translations, you must edit MAKEUNIX.BAT to include the new languages so that they are included in the PSAPPSRV.RES file.

To run MAKEUNIX.BAT:

Open a DOS command prompt window.
Change the directory to your \PT810\RES directory.
Run the MAKEUNIX batch file.

MAKEUNIX doesn’t require that you pass the module or language name arguments; it compiles the UNIX/Linux application server resources for all languages and modules in one pass.

The output from MAKEUNIX.BAT, and PSAPPSRV.RES is placed in <PS_HOME>\APPSERV\UNIX. You must transfer PSAPPSRV.RES to the BIN directory of your UNIX/Linux application server using a network file transfer utility, such as FTP.

Translating Objects

Not all translatable elements used internally by PeopleTools can be contained in resource files. Some strings referenced by Java and other components of PeopleTools are stored in Java-style property files. The PeopleSoft Pure Internet Architecture makes use of images for many navigational and user interface elements. Some of these images contain text which must also be translated.

This section discusses:

Translating property and text files.
Translating images.

Translating Properties Files

Java components of PeopleTools such as the servlets on the web server derive some strings from Java-style properties files. Java properties files are simple text files that are read at runtime by the servlet and contain strings that are displayed to the user, typically in error messages.

These files can be translated using any standard text editor, and are located on the web server. The following files contain translatable text:

Base Properties File	Translated Properties File
text.properties	text_<language_code>.properties
errors.properties	errors_<language_code>.properties

The base version of the file (without a language code) contains the English version of the strings. Copy this file to a new file containing the language code of your target language before translating the contents. For example, if you are translating the resources into Quechua, you would create text_QUE.properties and errors_QUE.properties, and update these files with Quechua translations of the contents.

See Adding New Languages.

When translating into a language that cannot be represented by the Latin-1 character set, such as Japanese, Chinese and Korean, the contents of the Java properties files must be converted into escaped Unicode character references. The Sun Java Development Kit (JDK) contains the native2ascii utility that you can use to convert Unicode character references in a Java properties file into a native character set and vice versa. Refer to the native2ascii utility documentation in the JDK for more information.

Translating Images

The PeopleSoft Pure Internet Architecture uses many images as part of its user interface component, and some of these images contain text. You will typically translate only images that contain textual elements or elements that are specific to one language or culture.

Translating an Image

To translate an image:

Change the PeopleSoft Configuration Manager language preference to the target language.
Open PeopleSoft Application Designer.
Open the image.

Choose File, Open and select the image you want to open.
Export the image to a file.

From the File menu select Export Image, and select a filename and image format to save the image to disk.
Use a graphics editor to modify the saved image file and update the translation.
From the Edit menu select Update Image.

A standard Open dialog box appears.
Open the file with the translated image.

The new graphic replaces the original graphic in the image.
Save the image.

The translated image is saved into the related language table under the language that you selected in the Configuration Manager in the first step.