# Native Language Support

This chapter identifies files used by the Help System that require modification when a help volume is provided in multiple languages.

HRDC.Lang.mkr.3
HRDC.Lang.mkr.5
HRDC.Lang.mkr.8
HRDC.Lang.mkr.9
HRDC.Lang.mkr.11
HRDC.Lang.mkr.14
HRDC.Lang.mkr.17
HRDC.Lang.mkr.18

## Internationalized Online Help

If your product is intended for an international audience, then providing online help in the user's native language is important. The Help System supports the authoring and displaying of online help in virtually any language.

When you process a help volume to create run-time help files, the DocBook software must be told what language and character set you used to author your files. The language and character set information is also used to determine the proper fonts for displaying the help volume.

## Internationalization Factors

Several factors, which are explained in the following section, contribute to providing effective online help in the user's native language.

### Character Sets

A character set determines how a computer's internal character codes (numbers) are mapped to recognizable characters. In most languages, single-byte characters are sufficient for representing an entire character set. However, there are some languages that use thousands of characters. These languages require two, three, or four bytes to represent each character uniquely.

Character sets supported by the Help System are listed in HRDC.Lang.mkr.6. However, some characters sets may not exist on all platforms.

### Common Desktop Environment Character Sets

Language | Character Set Name | Description
Western Europe and Americas | ISO-8859-1 | ISO Latin 1
HP-ROMAN8 | HP Roman
IBM-850 | PC Multilingual
Central Europe | ISO-8859-2 | ISO Latin 2
Cyrillic | ISO-8859-5 | ISO Latin/Cyrillic
Arabic | ISO-8859-6 | ISO Latin/Arabic
| HP-ARABIC8 | HP Arabic8
| IBM-1046 | PC Arabic
Hebrew | ISO-8859-8 | ISO Latin/Hebrew
| HP-HEBREW8 | HP Hebrew8
| IBM-856 | PC Hebrew
Greek | ISO-8859-7 | ISO Latin/Greek
| HP GREEK8 | HP Greek8
Turkish | ISO-8859-9 | ISO Latin 5
| HP-TURKISH8 | HP Turkish8
Japanese | EUC-JP | Japanese EUC (JISX0201, JISX0208, JISX0212)
| HP-SJIS | HP Japanese Shift JIS
| HP-KANA8 | HP Japanese Katakana8 (JISX0201 1976)
| IBM-932 | PC Japanese Shift JIS
Korean | EUC-KR | Korean EUC
Chinese | EUC-CN | Simplified Chinese EUC (China) (GB2312)
| EUC-TW | Traditional Chinese EUC (Taiwan) (CNS 11643.*)
| HP-BIG5 | HP Traditional Chinese Big5
| HP-CCDC | HP Traditional Chinese CCDC
| HP-15CN | HP Traditional Chinese EUC
Thai | TIS-620 | Thai

When writing DocBook files, you may use multibyte characters for any help text, but the DocBook markup itself (tag names, entity names, IDs, and so on) must be entered using eight-bit characters.

### DocBook Software

When you process a help volume to create run-time help files, the DocBook software must be told what language and character set you used to author your files. The language and character set information is used to determine the proper fonts for displaying help topics. If you do not specify a language and character set, DocBook assumes the default, which is English and ISO-8859-1.

The language and character set can be defined in the `LANG` environmental variable, or by using the Lang attribute of Part.

When writing DocBook files, you may use multibyte characters for any help text. However, the DocBook markup itself (tag names, entity names, IDs, and so on) must be entered using eight-bit characters.

### DtHelp

The menus, buttons, and labels that appear in help dialogs should also be displayed in the user's native language. To enable this, Help dialogs read such strings from a message catalog named `DtHelp.cat`. The message catalog source file, `DtHelp.msg`, contains strings for menus, buttons, and messages. If the language you need is not supplied, you must translate the sample message catalog (`/usr/dt/dthelp/nls/C/DtHelp.msg`) and then use the `gencat` command to create the run-time message catalog file. See HRDC.Lang.mkr.16 for instructions.

Refer to your system documentation to determine the correct directory where your new message catalog should be installed.

### LANG Environment Variable

The user's `LANG` environment variable is important for two reasons:

- The value of `LANG` is used to locate the correct help volume.

- When a help topic is displayed, the correct fonts and formatting rules are chosen based on the user's `LANG` variable. This is especially important for Asian languages that have word-wrap rules that are more sophisticated than European and American languages.

#### See Also

- Internationalization Programmer's Guide

- NLS documentation for your computer's operating system or programmer's kit

### Formatting Tables

A multibyte language, such as Japanese or Chinese, requires a formatting table. This table specifies a list of characters that cannot start a line and those characters that cannot end a line. When help files are processed, the formatting table ensures that lines wrap correctly. HRDC.Lang.mkr.14 explains how to create a new table or edit the sample table provided in the Help Developer's Kit.

### Font Schemes

One of the primary functions of the DocBook software is to convert your marked-up files into a run-time format that the Help System understands. Text is formatted by specifying particular attributes such as type family, size, slant, and weight. A font scheme is simply a name, like an alias, that the Help System uses to assign fonts to DocBook elements such as heads, procedures, lists, and so forth. It provides a way to map a group of text attributes used by the Help System with specific fonts.

Applications that use the standard Common Desktop Environment fonts do not need to define additional font resources. If your application relies on a different set of fonts, you must create and add a font scheme to your application.

#### See Also

- `DtStdInterfaceFontNames(5)` man page

- `DtStdAppFontNames (5)` man page

## Understanding Font Schemes

When you write a help volume using the DocBook markup language, you don't specify the fonts and sizes of the text. When you run the DocBook software, the elements that you've entered are formatted into run-time help files that include text attributes.

A font scheme maps text attributes to actual font specifications. For example, if a help topic is formatted using a bold, sans serif typeface, the font scheme identifies which Common Desktop Environment standard font or X font is actually used to display the text.

One of the primary uses of font schemes is to provide a choice of font sizes. The DocBook software formats the body of most topics as 10-point text. However, because the actual display font is determined by the font scheme being used, all 10-point text could be specified to use a 14-point font.

### Font Resources

Each font scheme is actually a set of X resources. These resources are read by the application displaying the help. If you want to change the font scheme, you can set font resources in your application's application defaults file.

Each resource within a font scheme has this general form:

*pitch.size.slant. weight.style. lang.char-set: font specification

Where:

pitch | Specifies the horizontal spacing of characters. This field should be either `p` (proportional) or `m` (monospace).
size | Specifies the height of the desired font. For help files formatted with DocBook, this value should be 6, 8, 10, 12, or 14.
slant | Specifies the slant of the desired font. Usually this field is either `roman` for upright letters or `italic` for slanted letters
weight | Specifies the weight of the desired font. Usually this field is either `medium` or `bold`.
style | Specifies the general style of the desired font. For help files formatted with DocBook, this value should be either serif or sans_serif.
lang | Specifies that volumes compiled using this language should use these fonts. Usually the entry uses an * (asterisk) so that all volumes using the specified char_set will use these fonts.
char-set | Specifies the character set used to author the help text. This value must match the character set that was specified when DocBook was run. The default is ISO-8859-1. Some special characters are displayed using a `symbol` character set.

An * (asterisk) can be used in a field to specify a font that has any value of that particular attribute. For instance, the symbol set (for special characters and special symbols) distinguishes a unique font based only on size and character set.

Its font resources appear like this within a font scheme:

    *.6.*.*.*.*.DT-SYMBOL-1:  -adobe-symbol-medium-r-normal-*-*-60-*-*-
    p-*-adobe-fontspecific
    *.8.*.*.*.*.DT-SYMBOL-1:  -adobe-symbol-medium-r-normal-*-*-80-*-*-
    p-*-adobe-fontspecific
    *.10.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-100-*-
    *-p-*-adobe-fontspecific
    *.12.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-120-*-
    *-p-*-adobe-fontspecific
    *.14.*.*.*.*.DT-SYMBOL-1: -adobe-symbol-medium-r-normal-*-*-140-*-
    *-p-*-adobe-fontspecific

The char-set field is the only field that cannot use the * (asterisk).

To display multibyte languages, such as Japanese or Korean, font resources must be specified using a font set. A font set is actually a group of fonts. A resource entry for a font set is similar to a single font, except that a , (comma) separates multiple font names and the specification ends with a : (colon). Here is an example of a fully specified font resource for a Japanese font set.

    bridge-gothic-medium-r-normal--18-180-75-75-c-80-jisx0201.1976-0,
    bridge-gothic-medium-r-normal--18-180-75-75-c-160-jisx0208.1983-0,
    bridge-gothic-medium-r-normal--18-180-75-75-c-160-jisx0212.1990-0:

You can also specify fonts for a multibyte language by providing a minimal XLFD font specification and allowing the system to supply the character set value to produce a font set.

    *.12.roman.medium.*.ja_JP.EUC-JP: -*-*-*-*-*-*-*-120-*-*-*-*-*-*:

When specifying a font set, remember to end the specification with a : (colon). This instructs the Help System to load a set of fonts to display the information. Font sets are used to display multibyte languages. For volumes containing single-byte information, use the standard font specification.

#### Sample Font Schemes

The `/usr/dt/dthelp/fontschemes` directory contains four font schemes:

`fontDef.fns` | Default fonts used by the Help System
`fontLarge.fns` | Example of a larger font
`fontMulti.fns` | Example of a multi-byte font
`fontX11.fns` | Example of standard X11 fonts

### To Choose a Font Scheme

Edit the application-defaults file for the application that displays the online help. Replace the current font resources (if any) with the new scheme.

If you are making this change just for yourself, copy the application-defaults file into your home directory before editing it.

#### Example

To use a larger size font (in the help dialogs) of a personal application named `DtStopWatch`, perform these steps:

Change to your home directory:

    cd

Then copy the `DtStopWatch` application-defaults file and make it writable:

    cp /usr/dt/app-defaults/C/DtStopWatch.
    chmod u+w DtStopWatch

Edit the `DtStopWatch`file to add the largest scheme (`fontLarge.fns`. Go to the end of the file, and insert the contents of this file:

`/usr/dt/dthelp/fontschemes/fontLarge.fns`

Save your new `DtStopWatch` file.

Start the `DtStopWatch` application, select Help, and verify that help topics are displayed using the new font scheme.

## Creating a Formatting Table

A multibyte language, such as Japanese or Chinese, requires a formatting table. This table contains three message sets. The first set consists of characters that cannot start a line; the second set lists any characters that cannot end a line; and the third set indicates how to handle newline characters that occur between a single-byte and a multibyte character.

A formatting table is an ASCII file whose file name must end with a `.msg` extension. HRDC.Lang.mkr.15 shows an excerpt from a formatting table for Simplified Chinese.

### Sample formatting table

Any line that begins with a $ (dollar sign) followed by a space is a comment.

### Sample Formatting Table

A sample formatting table for a multibyte character set is located in the `/usr/dt/dthelp/nls/zh_CN.dt-eucCN`directory and is named `fmt_tbl.msg.`

The sample table can be modified by adding or removing characters. To edit the formatting table, use an editor capable of composing characters in the language you have chosen for the help information. If you intend to create help information using a multibyte language, you need to create a formatting table.

### To Create a Message Catalog

If you translate the `DtHelp.msg` file, create a new formatting table, or modify the sample table (`fmt_tbl.msg`), you must update the message catalog used by the Help System.

Use this command syntax to generate the catalog file:

`gencat` file`.cat` file`.msg`

Message catalogs for the standard desktop applications are located in the `/usr/dt/lib/nls/msg/`lang directory. To install a message catalog, refer to your operating system documentation for guidelines.

#### See Also

- `gencat`(1) man page

## Displaying a Localized Help Volume

To view a help volume created for a locale different from your current system, you must set your `LANG` environment variable to match the help volume. The value of the `LANG` environment variable is platform-specific. If you are not familiar with this variable, check with your system administrator for the correct value and procedure to set your environment.

## Preparing Online Help for International Audiences

The following checklist summarizes the questions you should answer when providing online help for international audiences.

- Are help topics written with an international audience in mind?

- Was the DocBook software run using the correct `LANG` setting? If you author in another character set, you may have to translate the `DtHelp.msg` message catalog file and provide a font scheme that supports the new character set.

- Within your DocBook markup, are all tag names, entity names, and IDs entered using an eight-bit character set, even if the help text uses multibyte characters?

- When the user's `LANG` environment variable is set to the correct language, are the help files installed so they are found and displayed appropriately?

- If you have integrated the Help System into an application, have you properly set the locale using the `XtSetLanguageProc()` function?

### See Also

- HRDC.Inst.mkr.11

- `XtSetLanguageProc`(3) man page

- `gencat`(1) man page

- NLS documentation for your computer's operating system or programmer's kit