Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    Localizing a Palm OS Application

Palm OS® Resource Tools Guide

Palm OS® Developer Suite

This chapter describes how to use hOverlay to create localized versions of a Palm OS application (PRC file).

Introducing hOverlay ^TOP^

The hOverlay command line tool (hoverlay.exe) simplifies the process of localizing a Palm OS application (PRC file). It lets you create a base PRC that is not locale-specific, and then combine the base PRC with an "overlay" PRC that contains locale-specific information.

When localizing an application for a new locale, you need only create a new overlay PRC. The base PRC remains unchanged.


NOTE: Before reading this chapter, you need to know how to create a PRC. Specifically, you need to be familiar with XRD files, PalmRC, and PRCMerge. For information on PalmRC, see Chapter 3, "Compiling XML Resource Files." For information on PRCMerge, see Chapter 4, "Building a Palm OS Application." For information on XRD files, see the book Exploring Palm OS: Resource File Formats.

Preparing to Use hOverlay ^TOP^

Before using hOverlay, you need to split your PRC into multiple, separate PRC files:

  • a PRC that is not locale-specific (this is the non-localized PRC)
  • a locale-specific PRC for each desired locale (these are the localized PRC files)
Steps to Split your PRC
  1. Organize your application resources into multiple XRD files rather than just one:
    • The first XRD file should contain non-locale-specific resources such as the application icon and the version number; name this file something like MyApp_nonlocalized.xrd.
    • The second XRD file should contain locale-specific resources such as forms for one locale. For example, if this XRD file contain United States English resources, you might name it MyApp_enUS.xrd.
    • The third XRD should contain locale-specific resources for another locale. For example, if this XRD contains resources for France, you might name it MyApp_frFR.xrd.
    • If you wish, create more locale-specific XRD files (such as, for example, MyApp_jaJP.xrd for Japan, MyApp_deDE.xrd for Germany, and other locales).
  2. Use PalmRC to compile each XRD file, creating MyApp_nonlocalized.trc, MyApp_enUS.trc, MyApp_frFR.trc, and other locales.
  3. Use PRCMerge to link the TRC files with the appropriate code resources, creating PRC files named MyApp_nonlocalized.prc, MyApp_enUS.prc, MyApp_frFR.prc, and other locales.

You now have a non-localized PRC and multiple localized PRC files which hOverlay can use.

An alternative way to create a non-localized PRC and localized PRC files is to create a single XRD file for all your application resources, using the LOCALE attribute to indicate resources that pertain to a specific locale. You can then use the PalmRC overlayFilter parameter to create multiple, separate TRC files (a non-localized TRC and one or more overlay TRC files). Then use PRCMerge to link each TRC file with the appropriate code resources.

For detailed information on the LOCALE attribute, see Exploring Palm OS: Resource File Formats.

Understanding the hOverlay Process ^TOP^

hOverlay takes as input the non-localized PRC and localized PRC files that you created, and uses them to create a base PRC (BPRC) and overlay PRC files (OPRC). You can then install the base PRC (containing non-locale-specific information) and the appropriate overlay PRC (containing locale-specific information) on your device, and they work together like a single PRC.

The Palm OS Launcher application knows to treat the base PRC and overlay PRC files as a single application because they share the same database type and creator, and have the database bundle flag set. hOverlay uses the base PRC file's database header values (type, creator, version, and flags) to set the database header values in the output files. When hOverlay builds an OPRC file, it creates the database name automatically by appending the locale value to the base PRC file's database name. Also, hOverlay automatically sets the bundle flag for all the overlay database headers.

hOverlay can perform three different operations, which correspond to three different modes, described in the sections that follow.

Figure 6.1  hOverlay Mode 1

Mode 1: Creating a Base PRC

The first operation mode constructs the base PRC (BPRC). As input, it takes one non-localized PRC and one localized PRC (for information on creating these inputs, see "Preparing to Use hOverlay").

The locale of the localized PRC that you choose to use in mode 1 becomes the locale of the primary overlay PRC in Mode 2.

For example, you might choose to create your base PRC using the enUS (U.S. English) locale as the primary locale for this base PRC:

hOverlay -mode1 MyApp_nonlocalized.prc MyApp_enUS.prc enUS myApp.bprc

This example creates a base PRC using enUS as the primary locale.

Figure 6.2  hOverlay Mode 2

Mode 2: Creating a Primary Overlay PRC

The second operation mode constructs an overlay PRC (OPRC) for the same primary locale used with Mode 1. The parameters are the same, except that the output file name is the same as the name of the localized PRC for the primary locale.

For example:

hOverlay -mode2 MyApp_nonlocalized.prc MyApp_enUS.prc enUS myApp_enUS.oprc

This example creates an overlay PRC for the primary locale enUS.

Figure 6.3  hOverlay Mode 3

Mode 3: Creating Overlays for Other Locales

The third mode is used to construct overlay PRC files (OPRC) for locales other than the primary one. You must supply the following parameters as input:

  • the same non-localized PRC file that you used in modes 1 and 2
  • the same primary localized PRC file that you used in modes 1 and 2 (for example, if your primary locale is U.S. English, specify enUS here)
  • the localized PRC file for the specific locale (for example, if you are creating an overlay PRC for Japanese, specify jaJP here)
  • the name of the output overlay PRC file; this name is the same as the name of the localized PRC file for the specific locale. For example, if the localized PRC file that you used as input is MyApp_frFR.prc, the name of the output overlay PRC is MyApp_frFR.oprc.
Example

hOverlay -mode3 MyApp_nonlocalized.prc MyApp_enUS.prc MyApp_frFR.prc frFR MyApp_frFR.oprc

This example creates an overlay PRC for the frFR locale.

Using the hOverlay Command Line Tool ^TOP^

hOverlay is a Windows command line tool. hOverlay can be called from a batch file when building a PRC.

The command line syntax is as follows (in this example, the primary locale is enUS but you can use a different locale as your primary locale, if you wish):

hOverlay -mode1 nonlocalized.prc 
primary_locale.prc llCC 
output.bprc 


hOverlay -mode2 nonlocalized.prc primary_locale.prc llCC
output_llCC
.oprc
hOverlay -mode3 nonlocalized.prc primary_locale.prc secondary_locale.prc xxYY output_xxYY.oprc

Specifying Command Line Options ^TOP^

-mode1
This mode, -mode1, generates only the base PRC, which contains only the non-locale-specific resources.
-mode2
This mode, -mode2, generates only the primary locale's overlay PRC.
-mode3
This mode, -mode3, generates a specified locale's overlay PRC.
nonlocalized.prc
A PRC file containing only the non-locale-specific resources.
primary_locale.prc
A PRC file containing only the localized resources for the primary locale (in this example, the primary locale is enUS, but it could be any locale).
secondary_locale.prc
A PRC file containing localized resources for some locale other than the primary locale.
llCC
The primary locale associated with the primary_locale.prc file. In most of the examples, this primary locale is enUS for United States English.
xxYY
The secondary locale associated with the secondary_locale.prc file.
output.bprc
The filename of the base PRC to be generated by hOverlay. For example, this could be myprc.bprc.
output_llCC.oprc
The filename of the primary locale's overlay PRC, to be generated by hOverlay. The output name should always include the locale. For example, this could be myprc_enUS.oprc.
output_xxYYY.oprc
The file name of another locale's overlay PRC, to be generated by hOverlay. The output file name should always include the locale. For example, myprc_frFR.oprc for French, or myprc_jaJP.oprc for Japanese.
-noOvlyWarn
Turns off warning messages when overlay resources already exist in the source BPRC and OPRC files. This flag works in mode3 only.