Common Desktop Environment: Internationalization Programmer's Guide

Appendix A
Message Guidelines


Contents of Appendix:
File-Naming Conventions
Cause and Recovery Information
Comment Lines for Translators
Programming Format
Writing Style
Usage Statements
Standard Messages
Regular Expression Standard Messages
Sample Messages
Refer to the information in this appendix to write messages that are easily internationlized.

File-Naming Conventions

The conventions used in naming files with user messages are discussed here. Usually, the message source file has the suffix .msg ; the generated message catalog has the suffix .cat . There may be other such files related to messages. The following criteria must be met for a file to have these suffixes:

Cause and Recovery Information

Whenever possible, explain to users exactly what has happened and what they can do to remedy the situation.

The message Bad arg is not very helpful. However, the following message tells users exactly what to do to make the command work:

Do not specify more than 2 files on the command line

Similarly, the message Line too long does not giver users recovery information. However, the following message gives users more specific recovery information:

Line cannot exceed 20 characters

If detailed recovery information is necessary for a given error message, add it to the appropriate place in online information or help.

See "Sample Messages" for samples of original and rewritten messages.

Comment Lines for Translators

A message source file should contain comments to help the translator in the process of translation. These comments will not be part of the message catalog generated. The comments are similar to C language comments to help document a program. A dollar sign ($) followed by a space will be interpreted by the translation tool and the gencat command as comments. The following is an example of a comment line in a message source file.

$ This is a comment

Use comment lines to tell translators and writers what variables, such as %s , %c , and %d, represent. For example, note whether the variable refers to such things as a user, file, directory, or flag.

Place the comment line directly beneath the message to which it refers, rather than at the bottom of the message catalog. Global comments for an entire set can be placed directly below the $set directive in the source file.

Specify in a comment line any messages within the message catalog that are obsolete.

Programming Format

For the programming format of messages, see the following list.

Writing Style

The following guidelines on the writing style of messages include terminology, punctuation, mood, voice, tense, capitalization, and other usage questions.

Usage Statements

The usage statement is generated by commands when at least one flag that is not valid has been included in the command line. The usage statement must not be used if only the data associated with a flag is missing or incorrect. If this occurs, an error message unique to the problem is used.

Standard Messages

Certain commands have standard errors defined in POSIX.2 documentation. Follow the guidelines set up in POSIX.2, if applicable.

Regular Expression Standard Messages

Table A-2 lists the standard regular expression error messages, including the message number associated with each regular expression error:

Table A-2 Regular Expression Standard Messages

Sample Messages

These are examples of original messages and rewritten messages. The rewritten message follows each original message.

AFLGKEYLTRS "Too Many -a Keyletters (Ad9)"
AFLGKEYLTRS "foo: 7777-007 Use the -a flag less than 11 times.\n"

FLGTWICE "Flag %c Twice (Ad4)" FLGTWICE "foo: 7777-004 Use the %c header flag once.\n"

ESTAT "can't access %s.\n" ESTAT "foo: 7777-031 Cannot find or access %s.\n"

EMODE "foo: invalid mode\n" EMODE "foo: 7777-033 A mode flag or value is not correct.\n"

DNORG "-d has no argument (ad1)" DNORG "foo: 7777-001 Specify a parameter after the -d flag.\n"

FLOORRNG "floor out of range (ad23)" FLOORRNG "foo: 7777-021 Specify a floor value greater than 0\n\ \tand less than 10000.\n"

AFLGARG "bad -a argument (ad8)" AFLGARG "foo: 7777-006 Specify a user name, group name, or\n\ \tgroup number after the -a flag.\n"

BADLISTFMT "bad list format (ad27)" BADLISTFMT "foo: 7777-025 Use numeric version and release\ \tnumbers.\n"



Generated with CERN WebMaker