3. Using the Kit

Understanding the Localization Notes

Each DOG file associated with a. dll or .exe has the same name as the binary file, but will have the extension .DOG.

E.g. RESDLL.DLL has an associated RESDLL.DOG

Field Name	Purpose
FILENAME	Not used.
IDENTIFIER	Resource ID.
US_STR	Original English string.
XL_STR	Target translated string.
COMMENT	Localization notes for translator.
REASON	Explanation of leveraging results.
TRANSLATE	Resource is forbidden from translation if this is "FALSE"

Resource IDs are made up of a combination of the resource type and a unique identifier, depending on the type of resource. See the individual sections dealing with each resource type for a description of how resources are identified. You must not change the contents of this field.

The original English string is what you need to translate; however, your translation must go in the XL_STR field. It is not useful to change the contents of the US_STR field.

Your translation will be done in the XL_STR field. If there is no leveraged translation from a prior version, this string will originally match the US_STR value.

If a resource requires some extra explanation, this can be found in the COMMENT field.

The REASON field indicates the results of the leveraging process which created the database, which in turn was used to generate the .DOG file. Unless you are using the Netscape translation tools, this field is not useful to you.

The TRANSLATE field dictates whether or not you can change the value of the XL_STR field. If this field is blank, the resource is OK to translate; if the value is "FALSE", you must not translate it. (When viewed through ToolCool, this field appears as a check box. When checked, you may translate this resource; when unchecked, you may not.)

The next section presents the basic localization process as a checklist.

Localization Checklist

1. Create your working directories
Copy the English directory (kitRoot\products\client\windows\platform\en) to a new directory at the same level. Be sure to use the appropriate naming convention for your new directory. This is the ISO 639:1988 standard (Code for the representation of names of languages). A sub-set of these codes can be found in the accompanying table. You can go here for a complete listing of the standard.

2. Identify files to localize
Consult the Localize These Files page to learn which binary files contain localizable resources.

For each file to be localized, follow these steps using the tool of your choice, being careful to follow all instructions contained in the Localization Notes for that resource.:

• Localize the STRINGTABLE resources
• Localize the MENU resources
• Localize the DIALOG resources
• Localize the Javascript preferences stored in DATA resources (RESDLL.DLL only)
• Localize the remaining DATA resources (RESDLL.DLL only)

4. Complete post-translation processing
After translation is complete, you need to test your work and deal with any problems:

• Test the localized product.
• Fix translation bugs using your localization tools or a resource editor.
• Fix dialog size bugs using your localization tools or a resource editor.
• Report core bugs to Netscape.

• Return the necessary files to Netscape (if required).
• Inform us that the localized files have been returned (if required).

Product Branding Issues

How to Localize Different Resource Types

Localizing URLs

Many resources of all types in the Communicator contain Internet addresses in the form of URLs (Universal Resource Locators). Because many of these URLs originally point to locations within the Netscape domain, how they are localized depends on whether you are creating a branded Netscape version or not. The rules for how to handle URLs are found here.

Localizing String Tables

STRINGTABLE resources are the most sensitive, potentially problematic resource type you will be working with. Therefore, you must pay close attention to the instructions provided in the localization notes.

Localization Notes

String table resources are identified by the word STRINGTABLE, followed by the numeric resource ID generated from the project's header files. For example, in the file BRPREF32.DLL, STRINGTABLE109 contains the label and explanatory text for the Languages pane of the preference dialog. Localization notes for string table resources are provided in the comments field for each resource contained in the associated .DOG file. Please pay special attention to these notes and to the TRANSLATE field. In general, be aware of the following:

• Many strings contain C++ print format strings, such as %s, %ld, %lu, etc. Do not modify these while translating the rest of the string.
• Many strings contain new line characters: \n. In general, you should try leave these as you find them. In some cases, the new line is used to delimit a matched set of strings used to build a button label, a ToolTip and a status bar message all relating to single control. In these cases, you must preserve the new line characters.
• Many strings actually show up as part of an HTML or Javascript document or dialog. Be careful not to break format tags, like <TITLE>, <FONT>, etc. by translating these.

Localizing Menus

Menu translation is usually not as tricky as localizing string tables; however, you should take care to assign unique pickletters to menu choices. This process can be made difficult by the fact that some strings that appear in menus at runtime actually come from string tables. The special ID Build provided in this kit can help you find these.

Localization Notes

Menu resources are identified first by the word MENU, then by a resource number, then by a sequential Item number. For example, in RESDLL.DLL, MENU2ITEM0 contains the word "&File". This resource is the first item in menu structure structure #2 (the File menu). The ampersand character (&) denotes the pickletter is the letter "F". Localization notes for individual MENU resource items are provided in the comments field for that item in the localization databases. Not all MENU resource items need to be translated so again, please pay special attention to these notes and to the TRANSLATE field!

Localizing Dialogs

Dialog translation is usually not as tricky as localizing string tables; however, you should take care to assign unique pickletters to dialog controls. This process can be made difficult by the fact that some strings that appear in menus and dialogs at runtime actually come from string tables. The special ID Build provided in this kit can help you find these. Once a DIALOG resource has been translated, the dialog may need to be resized using a visual resource editor, such as MSDEV (Microsoft^® Visual C++ 4.0 or greater) or Borland^® Resource Workshop.

Localization Notes

Dialog resources are identified first by the word DIALOG , then by a resource number, then by a sequential Item number. For example, in NSMAILUI.DLL, DIALOG129Item0 contains the word "Password". This resource is the first item (the dialog title) in DIALOG129. Localization notes for individual DIALOG resource items are provided in the comments field for that item in the localization databases. Not all DIALOG resource items need to be translated so again, please pay special attention to these notes and to the TRANSLATE field!

A special note on Dialog fonts:
The second item in each dialog definition (e.g. DIALOGnnnITEM1) is the font information for that dialog. If you find it necessary to change the font name or size, be aware of the following fact: the font size is represented in the translation database by the ASCII character corresponding to that size. In the US product the default font size is 9, which appears as a Horizontal Tab (Font size = 9 = ASCII character 9 = tab). In the database, this will appear as an unprintable character, such as a black box. There are two concerns here: first, if you change the font name, be careful not to accidentally delete the tab character. Second, if you decide to change the font size, you can do so by substituting the appropriate ASCII character which matches the new size you want. For example, to change the font size to 10, replace the tab with a Line Feed character (ASCII 10). This is rather confusing, so it is probably best to avoid changing the fonts if possible.

Localizing Javascript Preferences

Javascript is used to define default preference information for the Communicator and it's components. These preferences end up stored in the DATA section of RESDLL.DLL. You can use the ToolCool to edit these just as you would STRINGTABLE resources, or use your preferred localization tools.

There are two groups of localizable Javascript preferences: ALL_PREFS and CONFIG_PREFS. Most of these preference settings are not localizable; these are marked as forbidden in the localization notes. Those that are localizable should be treated very carefully, as Javascript is rather particular about the format of the data it receives. Pay special attention not to unbalance quotes, delete the preceding tab characters, etc.

Localization Notes for ALL_PREFS

The entries in the ALL_PREFS section contain the default values for certain cross-platform preferences, including some crucial for the correct operation of localized versions. The rules for how to handle this section are found here.

Localization Notes for CONFIG_PREFS

The entries in the CONFIG_PREFS section make up the configurable Toolbar and Help menu items and their functions. How they are localized depends on whether you are creating a branded Netscape version or not. The rules for how to handle this section are found here.

Localizing DATA

There are several additional resources stored as DATA that cannot be edited using ToolCool. Therefore, you must use a resource editor and a text editor to localize these by following this procedure. (This example uses Microsoft^® MSDEV; if you prefer a different resource editor you may need to execute slightly different steps).

• Open the file containing the DATA resources (usually RESDLL.DLL)
• Expand the DATA resource type.
• Select the resource you want to localize
• Choose Edit | Select All.
• Choose Edit | Copy.
• Open a text editor window by clicking on the new document icon (or if you prefer, you may use any other text editor).
• Choose Edit | Paste.
• You should now have the text representation of the DATA resource in your text editor window. You may localize it according to the instructions in the Localization Notes section for each DATA resource.
• When done, save your work, then select ALL the text (use Edit | Select All if your editor supports this).
• Choose Edit | Copy.
• Go back to the RESDLL.DLL in MSDEV and select the DATA resource you have translated.
• Choose Edit | Select All.
• Choose Edit | Paste.
• You should now see the original English DATA resource replaced by your translated version.
• IMPORTANT: Go to the end of the resource and insert a NULL value by typing the number zero (0) in the first empty byte position.
• Close the resource and save your work.

Consult the Localize These Files to see the list of DATA resources that require localization:

Localizing External Files

As mentioned above, you may choose (or be required) to translate several external files. If this is the case, the links contained in the text file section of Localize These Files will tell you what to do. (Note: this may be nothing at all).

Localizing the NULL Plugin

The so-called "NULL" plugin is the default plugin that ships with all versions of the Communicator. It's job is to list the plugins that you have installed, and if you don't have a requested plugin, to help you get it.

The name and location of the NULL plugin is given in the Localize These Files binary file section. Localization notes have been provided for you to use when localizing the resources for this file. Instructions for individual resources can be found in the COMMENT field of the matching .DOG file.

---

Notes

1. Whether or not you have to incorporate or create localized version of these files depends on your agreement with Netscape, if any; or if localization is occurring as part of the Universal Localization Program, upon your desire to perform this work.[BACK]