# Configuring Localized Desktop SessionsNational Language Supportinternationalizing

To configure localized desktop sessions, you will need to:

- Set the LANG environment variable and other National Language Support (NLS) environment variables

- Access language-dependent message catalogs and resource files

- Execute applications remotely across internationalized systems

  SAG.I18N.div.2
  SAG.I18N.div.9
  SAG.I18N.div.10
  SAG.I18N.div.11
  SAG.I18N.div.12
  SAG.I18N.div.15
  SAG.I18N.div.16
  SAG.I18N.div.17
  SAG.I18N.div.18

## Managing the LANG Environment Variable

The LANG environment variable must be set for the desktop to use the operating system's language-sensitive routines. The desktop supports:

- Western Europe, Latin-based languages

- Japanese

- Traditional Chinese

- Simplified Chinese

- Korean

Support for other languages may have been added by your desktop vendor.

You can set LANG to any value supported by the operating system. The Options menu in the login screen displays the list of supported languages and territories.

There are four ways to set LANG for the desktop:

- By editing a resource in the `Xconfig` file

- Using the Options menu in the login screen

- By creating an executable `sh` or `ksh` `Xsession.d` script. (See SAG.SesMg.mkr.5 for more information about using an Xsession.d script.)

- By editing the user's `.dtprofile` file

When LANG is set, the desktop uses the following language-dependent files to determine the localized interface.

Colors | `/usr/dt/palettes/desc`.language
`Backdrops` | `/usr/dt/backdrops/desc`.language

### Setting the Language for Multiple Users

If you set the language by means of an `Xconfig` file, the login screen is localized and LANG is set for all users. This is the only way to change LANG for all displays in multi-display systems. (To modify `Xconfig`, copy `/usr/dt/config/Xconfig` to `/etc/dt/config/Xconfig.)`

The language is set by placing the following line in `/etc/dt/config/Xconfig`:

    dtlogin.host_display.language: language

For example, the following line sets LANG to `Swedish_locale` on display `my_host:0`.

    dtlogin.my_host_0.language: Swedish_locale

The `dtlogin` client reads the appropriate message catalog for that language and brings up the localized login screen. The `dtlogin` client then determines the list of locales using the following resources in the `/etc/dt/config/Xresources` resource file:

- `dtlogin*language`

- `dtlogin*languageList`

- `dtlogin*languageName`

The `Xconfig` file may need to set the NLSPATH environment variable appropriately for the chosen language. If this is not the case, or if you want to set NLSPATH yourself, see SAG.I18N.div.8.

### Setting the Language for One Session

To set the language for one session, use the login screen Options menu. The login screen is localized and LANG is set for the user. LANG returns to its default value (set in `dtlogin`) at the conclusion of the session.

### Setting the Language for One User

A user can override the login's LANG setting within the HomeDirectory`/.dtprofile` file. The login screen is not localized, and LANG is set for the user.

- If you use `sh` or `ksh`:

      LANG=language
      export LANG

- If you use `csh`:

      setenv LANG language

### LANG Environment Variable and Session Configuration

`The LANG environment variable changes the directory name that is searched for your session configuration files.`

`The localized session configuration files are:`

- `/usr/dt/config/`language`/Xresources` (Login Manager resource file)

- `/usr/dt/config/`language`/sys.font` (Session Manager resource file)

- `/usr/dt/config/`language`/sys.resources` (Session Manager resource file)

- `/usr/dt/config/`language`/sys.session` (Session Manager executable shell)

- `/usr/dt/config/`language`/sys.dtwmrc` (Window Manager resource file)

- `/usr/dt/appconfig/types/`language`/dtwm.fp` (Window Manager Front Panel)

### Setting Other NLS Environment Variables

Besides LANG, there are other NLS environment variables such as LC_CTYPE and LC_ALL. These variables are not affected by the `dtlogin` language resource nor by the login screen Options menu. They must be set in the following files:

- System-wide variables: `/etc/dt/config/Xsession.d`

- Personal variables: HomeDirectory`/.dtprofile`

#### NLSPATH Environment Variable

The NLSPATH environment variable determines the directory paths that applications search for message catalogs. Both LANG and NLSPATH must be set to use those message catalogs. Refer to SAG.I18N.div.16 for the location of localized messages. Most desktop clients will prefix the path to NLSPATH upon startup.

## Finding Fonts

Fonts included with the desktop are in the `/usr/lib/X11/fonts` directory.
Each directory contains a directory file, `fonts.dir`, and an alias file, `fonts.alias`. See the `mkfontdir` man page for information on creating the `fonts.dir` and `fonts.alias` files.

To list all fonts available at a server, user the `xlsfonts` command.
To add or delete fonts to the server, use the `xset` command.

## Managing User Defined Characters

### Overview

In East Asian countries such as China, Korea, and Japan, Chinese characters (called Hanzi in China, Hanja in Korea, and Kanji in Japan) are used extensively. Because the number of Chinese characters is very large (more than 50,000 in the largest Japanese Kanji dictionary) the standard coded character sets for Chinese characters (such as JIS X 0208, KS C 5601, and GB 2312) define only the most frequently used characters.

For ordinary writing purposes, a standard character set is sufficient. Some cases, however, require the use of non-standard characters. For example, for Resident Registration in Japan, a person's name and place name must be written in exactly the same characters as used in previously hand-written registration forms. Another example is the publication of ancient documents, such as Taoist or Confucian classics. These documents contain many characters that are now obsolete and not defined in the standard character sets. Such non-standard characters are referred to as "User Defined Characters."

#### How UDCs Are Organized

User Defined Characters (UDCs) use either "empty" code points (points in the code set that have no characters assigned to them) or a Private Use Area (if defined by the code set). In most cases, a system vendor will supply a UDC area, which consists of one or more contiguous blocks of code points that can be used for UDCs.

The basic procedure for creating a UDC is:

1. Assign a code point in the UDC Area to the character to be defined.

2. Create a glyph image (or a set of glyph images to define multiple font sizes) for that character by using the UDC Font Editor, `dtudcfonted`.

Once a UDC is created, it can be propagated to other systems by using the UDC Data Exchanger. For data interchange consistency, UDC definitions should be unified within an organization.

Before attempting to create UDCs, you must determine:

- What code set is being used and what code points are available for UDCs. To create UDCs, users must know which code points to use.

  When interchanging text data under the X Protocol, compound text is used. In compound text, extended segments can be used to transfer UDCs. If you use extended segments for UDC transfer, you should define the encoding name for the UDCs and how code points or glyph indexes are transferred in the segments.

- How font files are organized and what glyph indexes are used for UDCs. UDCs can be stored in standard font files with empty glyph indexes or in separate font files specific to UDCs. If separate files are used, the system should be shipped with empty font files for UDC. When editing an existing UDC, the user must specify the font name and the glyph indexes for the UDC. This means the user must know the relationship between code points and glyph indexes.

#### Font Files

To display and print UDCs they must be stored in databases as font files. UDC glyphs, like other character glyphs, are stored in font files that are used in the X Window system. The font file formats are PCF (Portable Compiled Format) and SNF (Server Natural Format), which can be accessed by an X server. The UDC Font Editor can also access font files in those formats.

When the X server displays a UDC, it refers to the UDC in the associated font file. Likewise, when a UDC is printed, the printer spooler refers to the UDC in the font file.

Font files must be set up to be able to be used by the X Window system. In other words, they must be placed in directories that are defined in the Xserver's font path, and the management files (such as fonts.dir) must be placed in those directories. The UDC Font Editor does not install font files, and does not modify any resources such as fonts.dir in the system.

The UDC Font Editor can use only UDC font files that are available in the current locale and that are defined in the X NLS database. The X NLS database is a database that defines what codeset and font set are used for each locale. The UDC Font Editor constructs UDC fonts in various point sizes and styles. To add a new editable font, you must specify the code set name and UDC area in the X NLS database.

When the UDC Font Editor and the UDC Data Exchanger look for font files, they first search the `DTUDCFONTPATH` environment variable (which is a colon-separated list of directories containing UDC font files) and then the directories specified in the `/usr/dt/config/$LANG/fonts.list` file. To set font search directories for each locale, specify them in the `fonts.list` file. (Do not forget the terminal colon.) For example:

    #
    # fonts.list file example
    #
      /usr/lib/X11/fonts/misc:
      /usr/dt/config/xfonts/ja:

### The UDC Font Editor

The UDC Font Editor (`dtudcfonted`) allows you to create, edit, and delete UDCs.

For complete details on using the UDC Font Editor, refer to the `dtudcfonted` man page.

When you start the UDC Font Editor, the `Font Selection` window appears.

UDC font files are specified by XLFD (X Logical Font Description) name. XLFDs are unique and descriptive font names that are used by clients and applications. The various font attributes such as style and a character set name are included in the XLFD. For convenience, you can select the font file style, size, and UDC code area. The UDC code area includes the code set number as specified in the X NLS database and the range of UDC glyph indexes that can be used in the code set.

To list the available UDC font files, select the code set, style, and definition character size of the desired font in the selection item field. Specifying a font and then selecting the `Open` button displays the `Character Edit` window.

#### Creating and Editing Characters

Character patterns are created or edited on the `Character Edit` window.

Select the code for the character to be edited from the character list. This displays the associated character pattern in the edit pane. If the character code has not been registered in in the UDC area, nothing is displayed.

If the character code has not been registered, add the code on the `Character Control` window, or copy the pattern on the `Character Copy` window. For details on how to add character codes, see "Adding and Deleting Character Codes". For details on how to copy character patterns, see "Copying Character Patterns".

A set of drawing tools and `Edit` menu options provide a complete set of operations for creating and editing character patterns.

#### Adding and Deleting Character Codes

Character codes are added and deleted on the `Character Control` window, which is displayed by choosing `Add/Delete` from the `Character` menu.

To add a character code, specify its four hexadecimal digits within the user-defined character area and click the `Add` button. You can also add a range of characters by specifying the codes for the first and last characters in the range. Each new character code is added to the list of characters being edited on the `Character Edit` window. The character to be edited is the first character of the added character code (or the added character code field). If already registered, the character pattern for the specified character code is not changed.

To delete a character code, specify its four hexadecimal digits within the user-defined character area and click the `Delete` button. You can also delete a range of characters by specifying the codes for the first and last characters in the range. The utility asks you to confirm each deletion.

Deleting a character code removes it from the list of characters being edited on the `Character Edit` window. The character code following the deleted character code becomes the current editable character code.

#### Entering Character Codes Graphically

To enter a character code graphically, click the `Code` button on the `Character Control` window. The `Character Code Input` window appears. On this window, click on the desired character, then click `Apply` to insert the code for the selected character in the code input field of the `Character Control` window.

#### Copying Character Patterns

To copy character patterns already registered or created, choose `Copy` from the `Character` menu. The `Character Copy` window appears. Copying adds the character code specified for the copy destination to the character list on the Editing window.

To copy a character pattern, select the character size and specify its four-hexadecimal-digit code. (You can also copy a range by supplying the codes for the first and last characters in the range.) Then, specify the four-hexadecimal-digit code(s) for the destination character(s) and click the `Copy` button.

You can also perform composite copies, in which the dots in the source character pattern are ORed with the dots in the destination character pattern.

### The UDC Data Exchanger

The UDC Data Exchanger (`dtudcexch`) is a tool for exchanging UDC glyph images between systems.

`dtudcexch` provides a mechanism for distributing UDC glyph images among different systems. Specifically, it allows UDC glyph images to be created on one system using the UDC Font Editor (`dtudcfonted`) and then propagated to other systems. `dtudcexch` stores the UDC glyph images in a BDF (Bitmap Distribution Format) file, which is transported to a target system. On the target system, `dtudcexch` is run again, this time to extract the images from the BDF file and add them to the appropriate font file.

`dtudcexch` provides both an export and an import function. The export function reads the selected UDC glyph images from a font file and stores them in a BDF file for transfer to other systems. The import function reads all UDC glyph images in a BDF file and adds them to a specified font file.

When exporting, `dtudcexch` uses glyph indexes of the UDC code area in the PCF/SNF font file to select the UDC glyph images. It stores the converted images in the BDF-format file at the same glyph indexes. When importing, `dtudcexch` adds the UDC glyph images to the PCF/SNF font file at the same glyph indexes found in the BDF file. The UDC code area information is defined in the X NLS database.

To create different glyph indexes for the images on the target system, you can edit the BDF file before you invoke the import function.

For details on using the UDC Data Exchanger, refer to the `dtudcexch` man page.

## Localizing app-defaults Resource Files

The default location for the `app-defaults` file for the desktop clients is `/usr/dt/app-defaults/`language. For example, if LANG is set to `Swedish_locale`, then applications will look for their `app-defaults` file in `/usr/dt/app-defaults/Swedish_locale`. If LANG is not set, language is ignored, and applications look for their `app-defaults` file in `/usr/app- defaults/C`.

To change the location of `app-defaults`, use the XFILESEARCHPATH environment variable. For example, to move `app-defaults` to `/users`, set XFILESEARCHPATH to `/usr/app-defaults/`language`/`classname.

If you set XFILESEARCHPATH in HomeDirectory`/.dtprofile`, the value applies to all desktop and X clients you run. Nonclients will not find their resource files unless you link or copy them into the directory specified by XFILESEARCHPATH.

## Localizing Actions and Data Types

To customize a file in the `/usr/dt/appconfig` directory, copy the file to the `/etc/dt/appconfig` directory prior to customizing.

The search path for action and data-type definition files includes language- dependent directories in:

- Personal: HomeDirectory`/dt/types`

- System-wide: `/etc/dt/appconfig/types/`language

- Built-in: `/usr/dt/appconfig/types/`language

The search path for Application Manager's configuration files is:

- Personal: Ho meDirectory`/dt/appmanager`

- System-wide: `/etc/dt/appconfig/appmanager/`language

- Built-in: `/usr/dt/appconfig/appmanager/`language

File and directory names in this directory are localized.

## Localizing Icons and Bitmaps

To localize an icon, edit the icon with Icon Editor and save it in:

    /etc/dt/appconfig/icons/language

If you save it in a different directory, set the XMICONSEARCHPATH environment variable to include the directory where you saved the icon. The XMICONBMSEARCHPATH environment variable controls the path used to search for icons.

## Localizing Backdrop Names

Localization of backdrops is done through the use of description files (`desc`.language and `desc.backdrops`). No specific localized directory exists (such as `/usr/dt/backdrops/`language) for backdrop files. All locales use the same set of backdrops files but have their own `desc.`language file containing the translated names of the backdrops.

The description file contains resource specifications for the backdrop names that are translated. For example:

    Backdrops*Corduroy.desc:    Velours
    Backdrops*DarkPaper.desc:   PapierKraft
    Backdrops*Foreground.desc:  AvantPlan

The `desc.`language file is used to retrieve the description of the backdrops for locale language in order to display the backdrop in the Style Manager. If there is a description specification, it will be displayed in the Style Manager backdrops list. Otherwise, the backdrop file name will be used.

Users can add their own backdrop descriptions in the HomeDirectory`/.dt/backdrops/desc.backdrops` file. This file is used to retrieve the backdrop descriptions for all backdrops added by the user regardless of locale.

The search path for the `description` files is:

- Personal: HomeDirectory`/.dt/backdrops/desc.backdrops`

- System-wide: `/etc/dt/backdrops/desc.`language

- Built-in: `/usr/dt/backdrops/desc.`language

## Localizing Palette Names

Localization of palettes is done through the use of description files (`desc`.language and `desc.palettes`). No specific localized directory exists (such as `/usr/dt/palettes/`language). All locales use the same set of palette files but have their own `desc.palettes` file containing the translated names of the palettes.

The description file contains resource specifications for the palette names that are translated. For example:

    Palettes*Cardamon.desc:    Cardamone
    Palettes*Cinnamon.desc:    Cannelle
    Palettes*Clove.desc:       Brun

The `desc.`language file is used to retrieve the description of the palettes for locale language in order to display the palette in the Style Manager list. If there is a description specification it will be displayed in the Style Manager palettes list. Otherwise, the palette file name will be used.

Users can add their own palette descirptions in the HomeDirectory`/.dt/palettes/desc.palettes` file. This file is used to retrieve the palette descriptions for all palettes added by the user regardless of locale.

The search path for the description files is:

- Personal: HomeDirectory`/.dt/palettes/desc.palettes`

- System-wide: `/etc/dt/palettes/desc.`language

- Built-in: `/usr/dt/palettes/desc.`language

## Localizing an Infolib

An infolib contains one or more bookcases, each of which contains one or more books that can be browsed and searched with the Information Manager. In this hierarchy, only the infolibs have associated desktop actions. As desktop entities, infolibs can be opened by dragging and dropping them on the Information Manager control. When an infolib is opened, the Information Manager displays the Book List window, showing all the bookcases contained in the infolib.

The default path for infolibs is set by the `DTINFOLIBPATH` environment variable. (The standard CDE desktop path is `/usr/dt/dtinfo/cde.dti`.) The name`.oli` file found at the first directory level of an infolib contains the abbreviated name for the infolib. Localizations of an infolib are found in subdirectories beneath the first directory level and are named according to the NLS mask %L (or %l_%t.%c.) In the Information Manager's Book List window, each bookcase in an infolib appears with the localized string or title stored in the `bookcase.map` file found in the bookcase's subdirectory.

## Localizing Help Volumes

If you have localized a help volume, you must store it in one of the following directories. The first help volume found is the one used. The directories are searched in the following order:

- Personal: HomeDirectory`/.dt/help`

- System-wide: `/etc/dt/appconfig/help/`language

- Built-in: /usr/dt/appconfig/help/language

## Localizing Message Catalogs

If you have localized a message catalog, store it in the following directory:

`/usr/dt/lib/nls/msg/`language.

These directories contain the `*.cat` files.

## Executing Localized Desktop Applications Remotely

You can invoke localized desktop applications on any remote execution host that has a similarly localized desktop installation. The values of the NLS- related environment variables on the host that is invoking the application are passed to the remote host when the application is started. However, the environment variables do not contain any host information.

## Resetting Your Keyboard Map

If you see unexpected characters and behaviors, or characters cannot be displayed or typed, you might need to reset or install your keyboard map or change your input method.

The input method is determined by the LC_CTYPE, LANG, or LC_ALL environment variables, or the language specified by the `-lang` option.

For example, if the user wants to open a terminal with the C locale within a POSIX shell, such as:

    LANG=C dtterm

This new terminal uses the C locale including the C input method and fonts. If you are using a language-specific keyboard, the input method may not accept any extended characters for input. When using the C locale with a language- specific keyboard, users need to set the LC_CTYPE (or LANG or LC_ALL) environment variable to an appropriate value before invoking the terminal.

For example, to use the C locale with the German keyboard, type:

    LANG=C LC_CTYPE=DeDE dtterm

If the X server has been reset and keymaps have been initialized, you can reset the proper keyboard map at the server using the `xmodmap` command.

## Selecting an Input Method Server

Asian users can select which input method server (IMS) to use either at session startup or at any time within a session (by using the Style Manager's Internationalization control). IMS selection is allowed only if `LANG` is set to an Asian language (Japanese, Korean, Chinese traditional, or Chinese simplified).

Once an IMS has been selected, users can set the IMS selection mode, which determines whether they will be prompted for an IMS at the next login or will automatically use the currently selected IMS.

The IMS selection and IMS selection mode are stored in the file:

    $HOME/.dt/ims/[display_name/]CDE_locale_name

The format of the IMS selection file is:

    @SelectMode:    0 (Ask at login), or
                    1 (Resume current input method)
    @ImsName:       ims_name
    @HostName:      host_name

### At Session Startup

To allow users to select an IMS prior to session startup, set the `DTSTARTIMS` environment variable to `TRUE`. Setting `DTSTARTIMS` to `TRUE` causes the Session Manager to execute the `/usr/dt/config/Xsession.d/0020.dtims` script. This script checks `LANG`. If `LANG` is set to an Asian language, the script invokes the `dtimsstart` program. `dtimsstart` displays an Input Method Selection dialog from which the user can select which IMS to use. The user can choose an IMS running either on the local host or on a remote host.

To set the selection mode, the user can use the Style Manager I18N control (described below) or use `DtActionInvoke` to execute the DtImsMode action in `Desktop_Tools` in the Application Manager. The DtImsMode action displays a dialog that lets the user choose either `Ask at Login` or `Resume current input method`.

The name of the selected IMS and its host and the selection mode are recorded in the IMS selection file.

### Within a Session

At any point within a session, a user can select which IMS to use by clicking the the Style Manager I18N control. (This control appears only if `LANG` is set to an Asian language.) The Input Method Selection dialog is displayed. If there is a current IMS, the dialog shows its name as well as the server host on which it is running. The user can choose an IMS that is running either on the local host or on a remote host.

To define the hosts on which an IMS can be found, you can configure the the `imServerHosts` application resource. The Style Manager uses this resource to identify which hosts to present for user IMS selection. It contains a comma-separated list of host names.

In addition to selecting the IMS, the user can set the selection mode to either `Ask at Login` or `Resume current input method`.

The name of the selected IMS and its host and the selection mode are recorded in the IMS selection file.

### Setting the IMS Configuration Files

In addition to the IMS selection file (described above), IMS configuration is defined by:

- The Locale Entry file

- The IMS Entry file

#### Locale Entry File

The Locale Entry file lists the IMSs that support a given locale. Its location is `/usr/dt/config/ims/`locale_name and it takes the format:

    @Default: ims_name
    ims_name: label_string
    …

The following shows a sample IMS listing for the locale `ja_JP.SJIS`:

    @Default: xjim
    xjim:     HP XJIM
    atok8:    ATOK8
    vje:      VJE-gamma
    egbridge: EGBridge
    none:     No Input Method

#### IMS Entry File

The IMS Entry file describes the attributes of an IMS. Its location is `/usr/dt/config/ims/` ims_name and it takes the format:

    attribute_name: attribute_value

where attribute_name is:

`protocols`

- A String attribute that identifies the supported XIM protocols. The valid protocols are XIM, Ximp, and Xsi. This attribute is required.

`server_name`

- A String attribute that identifies the server on which the IMS runs. This attribute is used for XMODIFIERS and is required.

`cmd_path`

- A Path attribute that specifies the absolute path of the the IMS's executable file. It is a a built-in keyword used for local IM built in Xlib, which does not need a separate process. This attribute is required.

`cmd_param`

- A String attribute that supplies a command line option for the IMS server. The default is NULL.

`env_set`

- A String attribute that specifies the environment variables to be set, with the exception of XMODIFIERS. The default is NULL.

`env_unset`

- A String attribute that specifies the environment variables to be unset, with the exception of XMODIFIERS. The default is NULL.

`env_pass`

- A String attribute that specifies the environment variables to be passed to a remotely executed IMS, with the exception of LANG, DISPLAY, and XMODIFIERS. The default is NULL.

`has_window`

- A Bool attribute that indicates whether the IMS has its own main window appearance or not. The default is False.

`no_server`

- A Bool attribute that indicates whether `dtimsstart` should start the IMS or not. True should be given for the local IM, since it does not require any server process started by `dtimsstart`. The default is False.

`no_remote`

- A Bool attribute that indicates whether the IMS allows remote execution or not. The default is False.

`no_option`

- A Bool attribute that indicates whether the IMS allows the command line option or not. If True, any options specified by `-imsopt` are ignored, though the value of the `cmd_param` attribute is always applied regardless of this value. True should be given for the local IM. The default is False.

Note that where multiple values are allowed, they must be specified as a space-separated list. If multiple entries with the same attribute name appear in the file, only the last one is used.

The following shows the contents a sample IMS entry file `/usr/dt/config/ims/`xjim.

    protocols:   XIM Ximp
    server_name: xjim
    cmd_path:    /usr/bin/X11/xjim
    cmd_param:   -iconic
    env_set:
    env_unset:
    env_pass:
    has_window:  true

## Setting Input Method Style

The Style Manager I18N control allows the user to set the input method style, which determines how pre-editing will occur. The order in which pre-edit styles will be used is stored in the XmNpreeditType resource of `VendorShell`. XmNpreeditType records the preferred order of pre-edit styles as a comma-separated list. For example:

    OnTheSpot,OverTheSpot,OffTheSpot,Root

By using the `Move-Up` and `Move-Down` buttons on the dialog displayed by the I18N control, the user can reorder the pre-edit styles within the list.