National Language Support (NLS) Quick Reference

The NLS Quick Reference provides a place to get started internationalizing programs. The following sections offer advice and a practical guide through the NLS documentation:

• National Language Support Do's and Don'ts lists NLS guiding principles.
• National Language Support Checklist provides a way to analyze a program for NLS dependencies.
• Message Suggestions lists some guidelines for creating clearer and maintainable messages.

National Language Support Do's and Don'ts

The following list presents a set of NLS guiding principles and advice. The intention is to prevent the occurrence of common errors when internationalizing programs. See the "National Language Support Overview for Programming" for more information about NLS.

• DO externalize any user and error messages. We recommend the use of message catalogs. X applications may use resource files to externalize messages for each locale. See the "Message Facility Overview for Programming" for more information.
• DO use standard X/Open, ISO/ANSI C, and POSIX functions to maximize portability. See "NLS Subroutines Overview" for more information.
• DO use the font set specification in order to be code-set independent in X applications.
• DO use Xm (Motif) library widgets for building bidirectional and character shaping applicaitons. See "Layout (Bidirectional) Support in Xm (Motif) Library" in AIX Version 4.3 AIXwindows Programming Guide for general information. Refer to the XmText or XmTextField widgets for support of input and output of bidirectional and shaping characteristics.
• DON'T assume the size of all characters to be 8 bits, or 1 byte. Characters may be 1, 2, 3, 4 or more bytes. See "Multibyte Code and Wide Character Conversion Subroutines" and the "Code Set Overview" for more information.
• DON'T assume the encoding of any code set. See the "Code Set Overview" for more information.
• DON'T hard code names of code sets, locales, or fonts because it may impact portability. See "National Language Support Overview for Programming" for more information.
• DON'T use p++ to increment a pointer in a multibyte string. Use the mblen subroutine to determine the number of bytes that compose a character.
• DON'T assume any particular physical keyboard is in use. Use an input method based on the locale setting to handle keyboard input. See the "Input Method Overview" for more information.
• DON'T define your own converter unless absolutely necessary. See the "Converters Overview for Programming" for more information.
• DON'T assume that the char data type is either signed or unsigned. This is platform-specific. If the particular system that is used defines char to be signed, comparisons with full 8-bit quantity will yield incorrect results. As all the 8-bits are used in encoding a character, be sure to declare char as unsigned char wherever necessary. Also, note that if a signed char value is used to index an array, it may yield incorrect results. To make programs portable, define 8-bit characters as unsigned char.
• DON'T use the layout subroutines in the libi18n.a library unless the application is doing presentation types of services. Most applications just deal with logically ordered text. See "Introducing Layout Library Subroutines" for more information.

National Language Support Checklist

The National Language Support (NLS) Checklist provides a way to analyze a program for NLS dependencies. By going through this list, one can determine what, if any, NLS functions must be considered. This is useful for both programming and testing. If you identify a set of NLS items that a program depends on, a test strategy can be developed. This facilitates a common approach to testing all programs.

All major NLS considerations have been identified. However, this list is not all-encompassing. There may be other NLS questions that are not listed. See "National Language Support Overview for Programming" for more information about NLS. See "National Language Support Do's and Don'ts" for a brief list of NLS advice.

Program Operation Checklist:

1. Does the program display translatable messages to the user, either directly or indirectly? An example of indirect messages are those that are stored in libraries.

   If yes:

   • Are these messages externalized from the program by way of the message facility subroutines?
   • Have you provided message source files for all such messages?
   • What is the locale under which the program runs?
     • If it runs in the locale determined by the locale environment variables, did you invoke the setlocale subroutine in the following manner?

       setlocale(LC_ALL, "")

       Note: See "Locale Subroutines" for setlocale subroutine examples. The locale categories, in their predefined hierarchical order, are: LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME. See "Localization" in "Locale Overview for Programming" for more information on the LC_ALL category.

     • If the program runs in the "C" locale, except for displaying messages in the locale specified by the locale environment variables, did you invoke the setlocale subroutine in the following manner?

       setlocale(LC_MESSAGES, "")

   • After invoking the setlocale subroutine, did you invoke the catopen subroutine in the following manner?

     catopen(catalog_name, NL_CAT_LOCALE)

   • Did you invoke the catopen subroutine with the proper catalog name?
   • See the "Message Facility Overview for Programming" for more information about translatable messages.
2. Does the program compare text strings?

   If yes:

   • Are the strings compared to check equality only?

     If yes:

     • Use the strcmp or strncmp subroutine.
     • Do not use the strcoll or strxfrm subroutine.
   • Are the strings compared to see which one sorts before the other, as defined in the current locale?

     If yes:

     • Invoke the setlocale subroutine in the following manner:

       setlocale(LC_ALL, "")

     • Use the strcoll, strxfrm, wcscoll, or wcsxfrm subroutine.
     • Do not use the strcmp or strncmp subroutine.
3. Does the program parse path names of files?

   If yes:

   • If looking for / (slash), use the strchr subroutine.
   • If looking for characters, be aware that the file names can include multibyte characters. In such cases, invoke the setlocale subroutine in the following manner and then use appropriate search subroutines:

     setlocale(LC_ALL, "")

4. Does the program use system names, such as node names, user names, printer names, and queue names?

   If yes:

   • System names can have multibyte characters.
   • To identify a multibyte character, first invoke the setlocale subroutine in the following manner and then use appropriate subroutines in the library.

     setlocale(LC_ALL, "")

5. Does the program use character class properties, such as uppercase, lowercase, and alphabetic?

   If yes:

   • Invoke the setlocale subroutine in the following manner:

     setlocale(LC_ALL, "")

   • Do not make assumptions about character properties. Always use system subroutines to determine character properties.
   • Are the characters restricted to single-byte code sets?

     If yes:

     • Use one of the ctype subroutines: isalnum, isalpha, iscntrl, isdigit, isgraph, isprint, isspace, or isxdigit.

       If not, the characters may be multibyte characters:

     • Use the iswalnum, iswalpha, iswcntrl, iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, or iswxdigit subroutine. See "Wide Character Classification Subroutines" for more information.
6. Does the program convert the case (upper or lower) of characters?

   If yes:

   • Invoke the setlocale subroutine in the following manner:

     setlocale(LC_ALL, "")

   • Are the characters restricted to single-byte code sets?

     If yes:

     • Use these conv subroutines: _tolower, _toupper, tolower, or toupper.
     If not, the characters may be multibyte characters:
     • Use the towlower or towupper subroutine. See "Wide Character Classification Subroutines" for more information.
7. Does the program keep track of cursor movement on a tty terminal?

   If yes:

   • Invoke the setlocale subroutine in the following manner:

     setlocale(LC_ALL, "")

   • You may need to determine the display column width of characters. Use the wcwidth or wcswidth subroutine.
8. Does the program perform character I/O?

   If yes:

   • Invoke the setlocale subroutine in the following manner:

     setlocale(LC_ALL, "")

   • Are the characters restricted to single-byte code sets?

     If yes:

     • Use following subroutine families:
       • fgetc, getc, getchar, getw
       • fgets, gets
       • fputc, putc, putchar, putw
       • printf, scanf
     If not:
     • Use following subroutine families:
       • fgetwc, getwc, getwchar
       • fgetws, getws
       • fputwc, putwc, putwchar
9. Does the program step through an array of characters?

   If yes:

   • Is the array limited to single-byte characters only?

     If yes:

     • Does not require setlocale(LC_ALL, "")
     • If p is the pointer to this array of single-byte characters, step through this array using p++.
   If not:
   • Invoke the setlocale subroutine in the following manner:

     setlocale(LC_ALL, "")

   • Use the mblen or wcslen subroutine.
   • See "Multibyte Code and Wide Character Code Conversion Subroutines" for more information.
10. Does the program need to know the maximum number of bytes used to encode a character within the code set?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Use the MB_CUR_MAX macro. See "Multibyte Code and Wide Character Code Conversion Subroutines" for examples using this macro.
11. Does the program format date or time numeric quantities?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Use the nl_langinfo or localeconv subroutine to obtain the locale-specific information.
    • Use the strftime or strptime subroutine.
    • See "Locale Subroutines" and "Monetary Formatting Subroutines" for more information.
12. Does the program format numeric quantities?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Use the nl_langinfo or localeconv subroutine to obtain the locale-specific information.
    • Use the following pair of subroutines, as needed: printf, scanf.
13. Does the program format monetary quantities?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Use the nl_langinfo or localeconv subroutine to obtain the locale-specific information.
    • Use the strfmon subroutine to format monetary quantities.
    • See "Locale Subroutines" and "Monetary Formatting Subroutines" for more information.
14. Does the program search for strings or locate characters?

    If yes:

    • Are you looking for single-byte characters in single-byte text?
      • Does not require setlocale(LC_ALL, "")
      • Use standard libc string subroutines such as the strchr subroutine.
    • Are you looking for characters in the range 0x00-0x3F (the unique code-point range) ?
      • Does not require setlocale(LC_ALL, "")
      • Use standard libc string subroutines such as the strchr, strcspn, strpbrk, strrchr, strspn, strstr, strtok, and memchr subroutines.
    • Are you looking for characters in the range 0x00-0xFF?
      • Invoke the setlocale subroutine in the following manner:

        setlocale(LC_ALL, "")

      • Two methods are available:

        Use the mblen subroutine to skip multibyte characters. Then, on encountering single-byte characters, check for equality. See checklist item 2.

        OR

        Convert the search character and the searched string to wide character form, and then use wide character search subroutines. See "Multibyte Code and Wide Character Code Conversion Subroutines" and "Wide Character String Search Subroutines" for more information.

15. Does the program perform regular-expression pattern matching?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Use the regcomp, regexec, or regerror subroutine.
16. Does the program ask the user for affirmative/negative responses?

    If yes:

    • Invoke the setlocale subroutine in the following manner:

      setlocale(LC_ALL, "")

    • Put the prompt in the message catalog. Use the catopen and catgets subroutines to retrieve the catalog and display the prompt.
    • Use the rpmatch subroutine to match the user's response.
    • See the "Message Facility Overview for Programming" for more information.
17. Does the program use special box-drawing characters?

    If yes:

    • Do not use code set-specific box-drawing characters like those in IBM-850.
    • Instead use the box-drawing characters and attributes specified in the terminfo file.
18. Does the program perform culture-specific or locale-specific processing that is not addressed here?

    If yes:

    • Externalize the culture-specific modules. Do not make them part of the executable program.
    • Load the modules at run time using subroutines provided by the system, such as the load subroutine.
    • If the system does not provide such facilities, link them statically but provide them in a modular fashion.

AIXwindows CheckList

The remaining checklist items are specific to the AIXwindows systems.

1. Does your client use labels, buttons, or other output-only widgets to display translatable messages?

   If yes:

   • Invoke the * XtSetLanguageProc subroutine in the following manner:

     XtSetLanguageProc(NULL, NULL, NULL);

   • Messages can be placed in either message catalogs or localized resource files. See checklist items 1 or 20, respectively.
   • To make the widgets code set-independent, specify fonts that use font sets.
2. Does your client use X resource files to define the text of labels, buttons, or text widgets?

   If yes:

   • Put all resources that need translation in one place.
   • Consider using message catalogs for the text strings. See the "Message Facility Overview for Programming" for more information.
   • Do not use translated color names, since color names are restricted to one encoding. The only portable names are encoded in the portable character set.
   • Put language-specific resource files in /usr/lib/X11/%L/app-defaults/%N, where %L is the name of the locale, such as fr_FR, and %N is the name of the client.
3. Is keyboard input localized by language?

   If yes:

   • Invoke the * XtSetLanguageProc subroutine in the following manner:

     XtSetLanguageProc(NULL, NULL, NULL);

   • Use the XmText or XmTextField widgets for all text input.

     Some of the XmText widgets' arguments are defined in terms of character length instead of byte length. The cursor position is maintained in character position, not byte position.

   • Are you using the XmDrawingArea widget to do localized input?
     • Use the input method subroutines to do input processing in different languages. See the "Input Method Overview" and the IMAuxDraw Callback subroutine for more information.
4. Does your client present lists or labels consisting of localized text from user files rather than from X resource files?

   If yes:

   • Invoke the * XtSetLanguageProc subroutine in the following manner:

     XtSetLanguageProc(NULL, NULL, NULL);

   • Use the XmStringCreateSimple subroutine to create the XmString data type for localized text. The XmStringCreate subroutine can be used, but XmSTRING_DEFAULT_CHARSET is preferable.
   • To make the widgets code-set independent, specify fonts by using font sets. Font resources (for example, * fontList: instead) in the app-defaults files should use the upper case and class form rather than the lower case form (for example, * FontList: instead). This allow the desktop style manager to affect the application font selection.
5. Does your program do any presentation operations (Xlib drawing, printing, formatting, or editing) on bidirectional text?

   If yes:

   • Use the XmText or XmTextField in the Xm (Motif) library. These widgets are enabled for bidirectional text. See "Layout (Bidirectional) Support in Xm (Motif) Library" in AIX Version 4.3 AIXwindows Programming Guide for more information.
   • If the Xm library can not be used, use the layout subroutines to perform any re-ordering and shaping on the text. See "Introducing Layout Library Subroutines" for more information.
   • Store and communicate the text in the implicit (logical) form. Some utilities (for example, aixterm) support the visual form of bidirectional text, but most NLS subroutines can not process the visual form of bidirectional text.

If the response to all the above items is no, then the program probably has no NLS dependencies. In this case, you may not need the locale-setting subroutine setlocale and the catalog facility subroutines catopen and catgets.

Message Suggestions

The following are suggestions on how to make messages meaningful and concise:

• Plan for the translation of all messages, including messages that are displayed on panels.
• Externalize messages.
• Provide default messages.
• Make each message in a message source file be a complete entity. Building a message by concatenating parts together makes translation difficult.
• Use the $len directive in the message source file to control the maximum display length of the message text. (The $len directive is specific to the Message Facility.)
• Allow sufficient space for translated messages to be displayed. Translated messages often occupy more display columns than the original message text. In general, allow about 20% to 30% more space for translated messages, but in some cases you may need to allow 100% more space for translated messages.
• Use symbolic identifiers to specify the set number and message number. Programs should refer to set numbers and message numbers by their symbolic identifiers, not by their actual numbers. (The use of symbolic identifiers is specific to the Message Facility.)
• Facilitate the reordering of sentence clauses by numbering the % s variables. This allows the translator to reorder the clauses if needed. For example, if a program needs to display the English message: The file % s is referenced in % s, a program may supply the two strings as follows:

  printf(message_pointer, name1, name2)

  The English message numbers the % s variables as follows:

  The file %1$s is referenced in %2$s\n

  The translated equivalent of this message may be:

  %2$s contains a reference to file %1$s\n

• Do not use sys_errlist[errno] to obtain an error message. This defeats the purpose of externalizing messages. The sys_errlist[] is an array of error messages provided only in the English language. Use strerror(errno) , as it obtains messages from catalogs.
• Do not use sys_siglist[signo] to obtain an error message. This defeats the purpose of externalizing messages. The sys_siglist[] is an array of error messages provided only in the English language. Use psignal() , as it obtains messages from catalogs.
• Use the message comments facility to aid in the maintenance and translation of messages.
• In general, create separate message source files and catalogs for messages that apply to each command or utility.

Describing Command Syntax in Messages

• Show the command syntax in the usage statement. For example, a possible usage statement for the del command is:

  Usage: del {File ...|-}

• Capitalize the first letter of such words as File, Directory, String, and Number in usage statement messages.
• Do not abbreviate parameters on the command line. For example, Num spelled out as Number can be more easily translated.
• Use only the following delimiters in usage statement messages:

  []	Encloses an optional parameter.
  {}	Encloses multiple parameters, one of which is required.
  |	Seperates parameters that cannot both be chosen. For example, [a|b] indicates that you can choose a , b , or neither a nor b ; and {a|b} indicates that you must choose a or b .
  ...	Follows a parameter that can be repeated on the command line. Note that there is a space before the ellipsis.
  -	Indicates standard input.

• Do not use any delimiters for a required parameter that is the only choice. For example:

  banner String

• Put a space character between flags that must be separated on the command line. For example:

  unget [-n] [-rSID] [-s] {File|-}

• Do not separate flags that can be used together on the command line. For example:

  wc [-cwl] {File ...|-}

• Put flags in alphabetical order when the order of the flags on the command line does not make a difference. Put lowercase flags before uppercase flags. For example:

  get -aAijlmM

• Use your best judgment to determine where you should end lines in the usage statement message. The following example shows a lengthy usage statement message:

  Usage: get [-e|-k] [-cCutoff] [-iList] [-rSID] [-wString] [-xList] [-b] [-gmnpst] [-l[p]] File ...

Writing Style of Messages

Clear writing aids in message translation. The following guidelines on the writing style of messages include terminology, punctuation, mood, voice, tense, capitalization, format, and other usage questions.

• Write concise messages. One-sentence messages are preferable.
• Use complete-sentence format.
• Add articles (a, an, the) when necessary to eliminate ambiguity.
• Capitalize the first word of the sentence, and use a period at the end of the sentence.
• Use the present tense. Do not use future tense in a message. For example, use the sentence:

  The cal command displays a calendar.

  Instead of:

  The cal command will display a calendar.

• Do not use the first person (I or we) in messages.
• Avoid using the second person (you) except in help and interactive text.
• Use active voice. The following example shows how a message written in passive voice can be turned into an active voice message.

  Passive: Month and year must be entered as numbers.
  Active:  Enter month and year as numbers.

• Use the imperative mood (command phrase) and active verbs such as specify, use, check, choose, and wait.
• State messages in a positive tone. The following example shows a negative message made more positive.

  Negative: Don't use the f option more than once.
  Positive: Use the -f flag only once.

• Use words only in the grammatical categories shown in a dictionary. If a word is shown only as a noun, do not use it as a verb. For example, do not solution a problem or architect a system.
• Do not use prefixes or suffixes. Translators may not know what words beginning with re-, un-, in-, or non- mean, and the translations of messages that use prefixes or suffixes may not have the meaning you intended. Exceptions to this rule occur when the prefix is an integral part of a commonly used word. For example, the words previous and premature are acceptable; the word nonexistent is not acceptable.
• Do not use parentheses to show singular or plural, as in error(s) , which cannot be translated. If you must show singular and plural, write error or errors. You may also be able to revise the code so that different messages are issued depending on whether the singular or plural of a word is required.
• Do not use contractions.
• Do not use quotation marks, both single and double quotation marks. For example, do not use quotation marks around variables such as % s, % c, and % d or around commands. Users may interpret the quotation marks literally.
• Do not hyphenate words at ends of lines.
• Do not use the standard highlighting guidelines in messages, and do not substitute initial or all caps for other highlighting practices. (Standard highlighting includes such guidelines as bold for commands, subroutines, and files; italics for variables and parameters; typewriter or courier for examples and displayed text.)
• Do not use the and/or construction. This construction does not exist in other languages. Usually it is better to say or to indicate that it is not necessary to do both.
• Use the 24-hour clock. Do not use a.m. or p.m. to specify time. For example, write 1:00 p.m. as 1300 .
• Avoid acronyms. Only use acronyms that are better known to your audience than their spelled-out version. To make a plural of an acronym, add a lowercase s without an apostrophe. Verify that the acronym is not a trademark before using it.
• Do not construct messages from clauses. Use flags or other means within the program to pass on information so that a complete message may be issued at the proper time.
• Do not use hard-coded text as a variable for a % s string in a message.
• End the last line of the message with \ n (indicating a new line). This applies to one-line messages also.
• Begin the second and remaining lines of a message with \ t (indicating a tab).
• End all other lines with \ n\ (indicating a new line).
• Force a newline on word boundaries where needed so that acceptable message strings display. The printf subroutine, which often is used to display the message text, disregards word boundaries and wraps text whenever necessary, sometimes splitting a word in the middle.
• If, for some reason, the message should not end with a newline character, leave writers a comment to that effect.
• Precede each message with the name of the command that called the message, followed by a colon. The following example is a message containing a command name:

  OPIE "foo: Opening the file."

• Tell the user to Press the ------ key to select a key on the keyboard, including the specific key to press. For example:

  Press the Ctrl-D key

• Do not tell the user to Try again later , unless the system is overloaded. The need to try again should be obvious from the message.
• Use the word "parameter" to describe text on the command line, the word "value" to indicate numeric data, and the words "command string" to describe the command with its parameters.
• Do not use commas to set off the one-thousandth place in values. For example, use 1000 instead of 1,000 .
• If a message must be set off with an * (asterisk), use two asterisks at the beginning of the message and two at asterisks at the end of the message. For example:

  ** Total **

• Use the words "log in" and "log off" as verbs. For example:

  Log in to the system; enter the data; then log off.

• Use the words "user name," "group name," and "login" as nouns. For example:

  The user is sam.
  The group name is staff.
  The login directory is /u/sam.

• Do not use the word "superuser." Note that the root user may not have all privileges.
• Use the following frequently occurring standard messages where applicable:

  Preferred Standard Message	Less Desirable Message
  Cannot find or open the file.	Can't open filename.
  Cannot find or access the file.	Can't access
  The syntax of a parameter is not valid.	syntax error

Related Information

National Language Support Overview for Programming. Locale Overview for System Management, How to Change the Language Environment, and How to Change Your Locale in AIX Version 4.3 System Management Guide: Operating System and Devices.

Code Set Overview, Code Set Strategy.

National Language Support Overview for System Management in AIX Version 4.3 System Management Guide: Operating System and Devices.

The chlang command, dspcat command, dspmsg command, gencat command, localedef , lslpp command, mkcatdefs command, runcat command in AIX Version 4.3 Commands Reference.

Understanding Code Set Strategy in AIX Kernel Extensions and Device Support Programming Concepts.

Character Set Description (charmap) source file format, Locale Definition source file format in AIX Version 4.3 Files Reference.

The environment file in AIX Version 4.3 Files Reference.