Appendix B Internationalization and CDE

This is a guide for software developers writing internationalized Solaris CDE applications. It presents the differences between OpenWindows and CDE internationalization. Any steps that must be performed to internationalize a Solaris CDE application that are not mentioned in this appendix remain unchanged from the OpenWindows guidelines. For general information on CDE and internationalization, see Common Desktop Environment: Internationalization Programmer's Guide.

• "Ensure Correct CDE NLS Environment"

• "Message Catalog Functions"

• "Locale Announcement"

• "Character Strings and XmStrings"

• "Include app-defaults File"

• "Localize Motif Resources"

• "Deliver Message Catalog"

• "Fonts"

• "Internationalizing Shell Scripts"

Solaris CDE supports all locales that Solaris 2.6 supports.

This appendix assumes familiarity with Xt and Motif programming.

Ensure Correct CDE NLS Environment

You must make sure that the NLSPATH environment variable is set properly. This ensures that your application will find message catalogs.

If your application calls DtInitialize(), then NLSPATH is set to the CDE default location for finding message catalogs. The default location is /<CDE_INSTALLATION>/lib/nls/msg/<locale>/<application>.cat; for example, /usr/dt/lib/nls/msg/ja/dtcm.cat.

DtInitialize() sets other variables and performs other tasks. Consult its manpage to determine whether you need this function. DtInitialize() is in libDtSvc. If your application does not already link to this library, you may not want to invoke DtInitialize() just to set NLSPATH.

If your application does not call DtInitialize(), you must set NLSPATH to ensure that your application can find message catalogs.

If your application installs or expects message files to be in a location other than the default location, you should append that location to NLSPATH.

Other CDE applications may not be able to find their message catalogs if you reset NLSPATH entirely. It is better to append to NLSPATH if your message file location differs from the default location.

Message Catalog Functions

To be portable to other XPG4 UNIX platforms, Solaris CDE applications must use the catopen(), catclose(), and catgets() family of XPG4 messaging functions (instead of gettext() and so on). See the man pages for information on how to use these functions.

Also, if the system on which you are writing your application does not define NL_CAT_LOCALE in a header file, you must define it in your application. This ensures that the application is portable to other UNIX XPG4-compliant platforms.

Locale Announcement

So that your application knows what locale it is running in, use:

• XtSetLanguageProc()--If your application is Motif/Xt GUI-based

• setlocale()--If your application is not GUI-based

Character Strings and XmStrings

This section describes how to convert between character strings and XmStrings.

To Convert from Character String to XmString

In Motif, you must make an explicit call to convert a string to XmString, an internal representation of the string. If you internationalize your application, use XmStringCreateLocalized() to perform this conversion.

In Solaris Motif--unlike in Motif 1.2.3--XmStringCreateLocalized() recognizes \n as a line separator, so a string can have multiple lines.

To Convert from XmString to Character String

To convert from XmString to a character string, you must traverse the compound string and retrieve each segment individually. See section 19.3.3 of the Motif Programming Manual, Volume 6A, which contains a code sample that performs this conversion.

Do not use XmStringGetLtoR() to convert from XmString to a character string. This function assumes the text is oriented left-to-right.

Include app-defaults File

If your application uses resources, make sure to include an app-defaults file. Refer to the X Toolkit Intrinsics Programming Manual (Volume 4, Section 2.3.3) for details on setting up an app-defaults file.

Localize Motif Resources

Localize any Motif resource that represents something that must be customized for a particular locale by putting the resource in your app-defaults file. These include, but are not limited to:

• XmNmnemonic

• XmNfontList

• XmNcolumns

• XmNinputMethod

• XmNpreeditType

Deliver Message Catalog

Every SVR4 UNIX platform contains the gencat utility. Run gencat on the translated message catalog file to produce a binary form of the message catalog. The resulting file is a formatted message database.

CDE and gencat

Each platform has its own implementation of gencat. Follow these rules for message catalogs to ensure that each message catalog's format does not cause different gencat utilities to break:

1. Use a $quote directive if you have trailing spaces (see the gencat man page).

2. Do not put more than one space between the message id and the message string.

3. Insert a space between $ and the comments.

4. Message IDs need to be sorted in ascending order.

.msg Files

A .msg file is a message catalog containing translatable text that appears in your application code. It is the file that you give to a translator for translation. See the gencat man page for its format. Use gencat to turn a translated message catalog to a message database.

.cat Files

A .cat file is a message catalog that results when you run gencat on a .msg file. This is a binary file.

Fonts

In the OpenWindows environment, font alias names differ depending on the application locale. In Solaris CDE, the font alias names are independent of locale. Refer to Common Desktop Environment: Internationalization Programmer's Guide or Solaris Common Desktop Environment: Programmer's Guide for information on CDE font names.

Internationalizing Shell Scripts

The dtdspmsg utility is useful for internationalizing shell scripts. The dtdspmsg command displays a selected message from a message catalog. See the dtdspmsg man page for details.