Introduction

Sun WorkShop Visual helps you to make use of the special features that X and Motif provide to assist in developing applications that can be used in different languages. Although internationalization is a complex subject, this chapter points you in the direction of those areas that you will need to examine in order to fully internationalize your software.

In order to type text of languages other than your own, you will need an X server which supports that language. You can find out if this is the case by checking whether the locale is present on your system. See "Locale Name" on page 621 for some hints on how to find out.

What is the Problem?

If your application is to be used by speakers of another language (even if that other language is British English rather than American English) you cannot assume that they understand your language and conventions. Apart from the variation in language, the use and style of addresses, date and time formats, personal names, even paper sizes may be very different from yours.

Scripts, in particular, can constitute a vast difference in the appearance and behavior of your application. Some languages, such as Korean, Japanese and Chinese, are ideographic. They do not have an alphabet as understood in Roman languages. Each word is represented in a graphical form. The fonts used to display such a script need to be able to handle thousands of these characters. This problem is discussed further in "Creating International Text" on page 624.

Other languages, such as Hebrew and Thai are alphabetic but still totally unlike Roman scripts. Some letters change according to context. There are often no spaces to distinguish words and some languages are written right to left while others are written left to right.

Even languages which appear to be very similar, such as French, English and German, involve differences in the symbols (or diacritics) used with letters and in the way in which letters are changed from lowercase to uppercase and vice versa.

X11 does assist you in addressing these problems by providing FontSets. These are explained in "Font Sets" on page 621. Also explained in this chapter is the mechanism by which input methods, required by non-alphabetic scripts, can be used in your application.

Although Japanese is used in most examples in this chapter, the principles are the same for any language.

It must be stressed here that this chapter aims to introduce you to the large area of internationalization and to explain how this is supported by Sun WorkShop Visual. You are strongly advised to refer to additional documentation for more in-depth information. This includes system documentation, Motif documentation and, where necessary, books such as those listed in Appendix  E, "Further Reading", starting on page 889.

Locale

Before you begin to address the issue of internationalization with regard to your application, you will need to understand how to set up your environment for a particular location. This involves an understanding of locales. A locale is an ANSI-C concept. It is a name that is used to identify a set of local information. For example, the locale might be set to be "en_UK" to denote that the location is the U.K. with English as the language, "en_US" for English as used in the U.S., or "ja" for Japanese. The setting of a locale makes certain C library functions operate in different ways, e.g. defining the sorting order, or date format.

Locale Name

You need to know the system name of the locale you are wishing to use and then set the LANG environment variable correspondingly so that applications can work out which language they should be displaying. Note that the name of the locale may differ depending on which system you are using. For a list of locale names supported by your UNIX system, look in the directory /usr/lib/locale. This will contain a directory for every language available. The directory names are used as the locale name, which is also the name you should use for the LANG environment variable. Type:

locale -a 

to list all locales currently installed on your system.

Specifying the Locale

To run Sun WorkShop Visual with internationalization support, you must set an appropriate locale. Do this by setting the LANG environment variable before running your X server, for example:

setenv LANG ja

This tells X to use Japanese for its display fonts and keyboard input, if Japanese is installed on your system.The value of the environment variable may be different on your system. See the Locale Name section above for more information.

For a language such as Japanese, which uses an input method in-between the keyboard and a text widget, you must make sure that you are running the appropriate version of Sun WorkShop Visual (in this case Japanese). This is because it is the presence of the Japanese fonts, in combination with the LANG environment variable, which indicates to the X server that an input method is required.

Font Sets

Part of a locale's definition includes a specification of the font encodings required in order to display all possible text. For example, the Japanese locale requires that fonts with codesets ISO 8859-1, JIS X0208-1983 and JIS X0201-1976 be present in order to display all text in the Japanese language because Japanese contains Roman characters, Japanese alphabet characters (kana) and ideographic characters (Kanji). A FontSet is a collection of Fonts that contains all the required character sets for the current locale.

FontLists

The FontList is a collection of Fonts which is used for drawing labels in multiple fonts and styles. FontLists are specific to Motif whereas FontSets are defined by X.

For example, in order to specify that a string contains both bold and italic, you create a compound string with markers indicating which font (bold or italic) to use where. This is easily achieved in the Sun WorkShop Visual XmString editor (see "Compound Strings" on page 167). To do so, however, you need to define a Font Object in the Font Editor (see "Setting Fonts" on page 143) which contains a list of fonts - one bold and one italic. This is your FontList. Each Font in the FontList is tagged with the name you specify in the Font Editor. These tags are included in the compound string to tell the X server which font to use.

What is the Connection Between FontSets and FontLists?

In order to incorporate FontSets, Motif has extended its definition of a FontList so that each entry in a FontList can be either a single Font (FontStruct) or a FontSet.

Sun WorkShop Visual simplifies this by presenting all the Fonts in a FontSet as straightforward members of the FontList. However, when you set the FontSet toggle in the Font Selection dialog, you are indicating to Sun WorkShop Visual that this Font is a member of a FontSet. Internally Sun WorkShop Visual gives all members of a FontSet the same FontList tag. Motif then collects together all Fonts with the same FontList tag as members of a FontSet.

See "Simple Font Objects" on page 148 for more information on font objects and "Creating a Complex Font Object" on page 168 for an explanation of FontLists.

Example of the Use of FontSets

The following exercise illustrates the use of FontSets.

The Japanese locale described above requires these three encodings:

ISO 8859-1 for Latin characters

JIS X0208-1983 for Kanji ideographic characters

JIS X0201-1976 for Kana phonetic characters

FIGURE  22-1 Missing Charsets Warning

FIGURE  22-2 Initial Font in FontSet

Font object entries can be deleted and re-bound regardless of whether or not they are part of a FontSet. A FontList can have many entries which can be either FontSets or simple fonts. To achieve this, specify different Fontlist tags and set the "Font set" toggle as appropriate. The following example shows a single font object that has three entries: t1, big and t2. t1 and t2 are complete FontSets for the ja locale; big is a simple font.

FIGURE  22-3 A Font Object with Three Entries.

Creating International Text

For a language such as Japanese, Chinese or Korean, more characters can be displayed than there are keys on the keyboard, or numbers that can be represented by 8 bits. In addition, text displayed by Japanese symbols must be mixed with Roman numerals and Roman text. These problems are addressed by coding the text in a special way. Instead of the familiar ASCII mapping, multi byte text strings are used in order to allow for the larger set of characters in these languages. Multiple characters in the text signify a single character from the matching font. The way in which one- and multi-byte characters are distinguished depends on the encoding. Such languages also have a one-to-many mapping of sound (as may be typed on the keyboard) and ideographic character. To resolve this, an input method is provided.

Languages such as Hebrew and Arabic also require an input method because the letters change according to the position in the word and vowels are written around the consonant.

If an input method is required and you are running an appropriately localized version of Sun WorkShop Visual, a special key sequence switches into using the input method when you enter text into a text field. The method converts the characters typed into corresponding characters in the target language.

Using an Input Method in Sun WorkShop Visual

To enter non-English text into any text input area in Sun WorkShop Visual first of all make sure that you fulfil the following requirements:

The following example illustrates how to type text in a language which requires an input method. The language used is Japanese. If you are using CDE:

If you are not useing CDE:

Whether you are using CDE or not, the following instructions are the same:

The procedure for other languages is similar - first, set the LANG environment variable, start your X server, then invoke Sun WorkShop Visual. For some languages and on some systems you may also need to start an input method or server. Refer to your system documentation to check whether this is necessary. The input method will appear whenever a window with a text area has the current focus.

For more information on international text on Sun platforms, see your Sun documentation.

Localized Input in Your Application

The previous section described how to enter non-ASCII text into Sun WorkShop Visual (for example into the label resource). This section describes how to enter localized text in your generated application. Note that the term "converted text" is used. This means any text on the screen which differs from that which appears on a standard keyboard.

How Text is Converted

The X toolkit does most of the work for you. What you need to do is to indicate to the X toolkit that a particular text widget will be receiving non-ASCII text. This is accomplished by fulfilling these criteria:

If the second condition above is true, the text widget makes a request to the enclosing Shell to establish a connection to the input method. The X toolkit then takes over, diverting text input for that text widget to the input method and returning to the text widget the resulting converted text.

Setting up A Text Widget to Receive Converted Text

You can see from above that in order for a text widget in your application to use an input method, all you have to do is to make sure that the text widget has a FontList specified for it which includes a FontSet matching the locale at creation time. The simplest way to do this is to use Sun WorkShop Visual to specify a font object containing an appropriate FontSet and use that as the font resource for the widget. The following steps illustrate this:

Seeing the Input Method in the Dynamic Display

Although the above works correctly for your generated application, there is a drawback. Sun WorkShop Visual always creates the widget before resources are applied to it, even on reset or paste. Therefore, to see the input method working in the dynamic display window, you must force the font to be specified at creation time. This is best accomplished by setting the textFontList resource on a parent Bulletin Board or Shell widget. Obviously, this has the disadvantage that all the child text widgets have the input method.

To see a text widget working with an input method from within Sun WorkShop Visual, use the following steps.

FIGURE  22-4 A Simple Dialog with Input Method Attached.

The default main() program includes a call to XtSetLanguageProc(), which initializes the locale handling routines. If you are writing your own main() program, you must insert a call to this routine if you are using any internationalization features. Add the following line to the beginning of your main() routine:

XtSetLanguageProc ( (XtAppContext) 0, (XtLanguageProc) 0, (XtPointer) 0 );

Setting the Application Font Resource

When using international text in Sun WorkShop Visual the text will not appear correctly in the dynamic display or generated application unless the appropriate FontList resource is set for the language you are using.

A useful way to implement the correct FontList settings on an application-wide basis is to use loose bindings to declare a FontList resource binding as in the following example:

---

Note - The line breaks in the following example have been inserted for clarity - if you are editing a resource file you must make sure that there are no line breaks, otherwise the resource setting will be ignored.

---

XApplication*FontList:

	-misc-fixed-medium-r-normal-*-14-130-75-75-c-140-

		jisx0208.1983-0;

	-*-*-medium-r-normal-*-14-130-75-75-c-70-jisx0201.1976-0;

	-misc-fixed-medium-r-normal-*-14-110-100-100

		-c-70-iso8859-1:default

where XApplication is the class name of your application. This example sets some Japanese fonts. The above example resource can be found in $VISUROOT/src/examples/loose_bindings/ja_fontlist.res and can be loaded into your design via the loose bindings dialog.

See "Loose Bindings" on page 87 for details on how to do this.

Using Eight-Bit Characters in Shell Titles

If you intend to use a character with the eighth bit set in the title string of a Shell widget, you must make sure that the titleEncoding resource is set to "STRING". You can do this from within Sun WorkShop Visual by specifying a loose binding which should look like this:

XApplication*titleEncoding:	STRING

(where XApplication is the class name of your application.)

Or this:

*titleEncoding:	STRING

depending on whether you wish the resource binding to apply to all applications (as in the second example) or just your own application.

See "Loose Bindings" on page 87 for details on how to do this.

Alternatively, if you prefer to "hard code" the setting of this resource in your design, you can set the pre-manage prelude for the main Shell as follows:

XtSetArg ( al[ac], XmNtitleEncoding, XA_STRING ); ac++;

See "Shell Pre-manage Prelude" on page 252 for details on adding a pre-manage prelude to a Shell widget.

Unsupported Locales

"Using an Input Method in Sun WorkShop Visual" on page 625 describes how you can specify a locale using the LANG environment variable. Providing you are using an appropriate version of Sun WorkShop Visual, you may then use the language of the locale for the strings in the user interface you are designing. If you have set your LANG environment variable to a locale which is not supported by your version of Sun WorkShop Visual, a message is displayed on startup informing you that your LANG setting is unsupported and that it is being coerced to "C". This is the default and is US English. If your Sun WorkShop Visual expects a Latin script¹, it will display and function correctly. The only area where there could be a problem is in strings in the generated code. If the following are true, you will be able to add labels, text strings etc. in the locale you specified:

The locale you specified for LANG uses a Latin character set

The appropriate font or fonts are available

The language of the specified locale does not require special processing (i.e. needs an input method or does not display left to right)

If, however, any of the above is not true, you will probably not be able to enter or display strings in the specified language.