Message Guidelines

Refer to the information in this appendix to write messages that are easily internationlized.

• File-Naming Conventions

• Cause and Recovery Information

• Comment Lines for Translators

• Writing Style

• Usage Statements

• Regular Expression Standard Messages

• Sample Messages

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.