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:

It is X/Open-compliant.
It becomes a *.cat file through the use of the gencat command.

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.

Do not construct messages from clauses. Use flags or other means within the program to pass information so that a complete message can be issued at the proper time.
Do not use hardcoded English text as a variable for a %s string in an existing message. This is also the construction of messages and is not translatable.
Capitalize the first word of the sentence, and use a period at the end of the sentence or phrase.
End the last line of the message with \n (backslash followed by a lowercase n, indicating a new line). This also applies to one-line messages.
Begin the second and remaining lines of a message with \t (backslash followed by a lowercase t, indicating a tab).
End all other lines with \n\ (backslash followed by a lowercase n, followed by another backslash, indicating a new line).
If, for some reason, the message should not end with a new line, use a comment to tell the writers.
Precede each message with the name of the command that called the message, followed by a colon. The command name should precede the component number in error messages. The command name is shown in the following example as it should appear in a message:
```
OPIE "foo: Opening the file."
```

Writing Style

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

Use sentence format. One-line and one-sentence messages are preferable.
Add articles (a, an, the) when necessary to eliminate ambiguity.
Capitalize the first word of the sentence and use a period at the end.
Use the present tense. Do not allow future tense in a message. For example, use the sentence:
```
The foo command displays a calendar.
```
Instead of:
```
The foo command will display a calendar.
```
Do not use the first person (I or we) anywhere in messages.
Avoid using the second person.
Do not use the word you except in help and interactive text.
Use active voice. The first line is the original message. The second line is the preferred wording.
```
MYNUM "Month and year must be entered as numbers."
MYNUM "foo: 7777-222 Enter month and year as numbers.\n"
```
7777-222 is the message ID.
Use the imperative mood (command phrase) and active verbs: specify, use, check, choose, and wait are examples.
State messages in a positive tone. The first line is the original message. The second line is the preferred wording.
```
BADL "Don't use the f option more than once."
BADL "foo: 7777-009 Use the -f flag only once.\n"
```
Do not use nouns as verbs. Use words only in the grammatical categories shown in the 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, for that matter, architect a system).
Do not use prefixes or suffixes. Translators may not understand words beginning with re-, un-, in-, or non-, and the translations of messages that use these 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. The words previous and premature are acceptable; the word nonexistent, is not.
Do not use plurals. 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. A better way is to condition the code so that two different messages are issued depending on whether the singular or plural of a word is required.
Do not use contractions. Use the single word cannot to denote something the system is unable to do.
Do not use quotation marks. This includes 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 take the quotation marks literally.
Do not hyphenate words at the end of lines.
Do not use the standard highlighting guidelines in messages, and do not substitute initial or all caps for other highlighting practices.
Do not use and/or. 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 versions. To make a plural of an acronym, add a lowercase s, without an apostrophe. Verify that it is not a trademark before using it.
Avoid the "no-no" words. Examples are abort, argument, and execute. See the project glossary.
Retain meaningful terminology. Keep as much of the original message text as possible while ensuring that the message is meaningful and translatable.

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.

Show the command syntax in the usage statement. For example, a possible usage statement for the del command reads:
```
Usage: del {File ...|-}
```
Clauses defining the purpose of a command are to be removed.
Capitalize the first letter of such words (parameters) as File, Directory, String, Number, and so on only when used in a usage statement.
Do not abbreviate parameters on the command line. It may be perfectly obvious to experienced users that Num means Number, but spell it out to ensure correct translation.
Use only the following delimiters in usage statements:

Delimiter
Description

[]
Parameter is optional.

{ }
There is more than one parameter choice, but one of the parameters is required. (See the following text.)

|
Choose one parameter only. [a|b] indicates that you can choose a or b or neither a nor b. {a|b} indicates that you must choose either a or b.

..
Parameter can be repeated on the command line. (Note that there is a space before the ellipsis.)

-
Standard input.
A usage statement parameter does not require square brackets or braces if it is required and is the only choice, as in the following:
```
banner String
```
In usage statements, put a space between flags that must be separated on the command line. For example:
```
unget [-n] [-rSID] [-s] {File|-}
```
If flags can be used together without a separating space, do not separate them with a space on the command line. For example:
```
wc [-cwl] {File ...|-}
```
When the order of flags on the command line does not make a difference, put them in alphabetical order. If the case is mixed, put lowercase versions first:
```
get -aAijlmM
```
Some usage statements can be long and involved. Use your best judgment to determine where you should end lines in the usage statement. The following example shows an old-style usage statement for the get command:
```
Usage: get [-e|-k] [-cCutoff] [-iList] [-rSID] [-wString] [xList] [-b] [-gmnpst] [-l[p]] File ...
Retrieves a specified version of a Source Code Control System (SCCS) file.
```

Standard Messages

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

Tell the user to Press the ------ key to select a key on the keyboard, including the specific key to press (such as, Press Ctrl-D).
Unless the system is overloaded, there is no need to tell the user to Try again later. That should be obvious from the message.
When writing message text, use the word parameter to describe text on the command line; use the word value to indicate numeric data.
Use the word flag rather than the words command option.
Do not use commas to set off the one-thousandth place in values.
Do not use 1,000. Use 1000.
If a message must be set off with an asterisk, use two asterisks at the beginning of the message and two asterisks at the end of the message.
```
** Total **
```

Use log in and log off as verbs.

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

Use user name, group name, and login as nouns.

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

User number and group number refer to the number associated with the user's name and group.
Do not use the term superuser. The root user may not have all privileges.
Use the words command string to describe the command with its parameters.
Many of the same messages occur frequently. Table A-1 lists the new standard message that replaces the old message.
Table A-1 New Standard Messages

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

Appendix AMessage Guidelines