Common Desktop Environment: Internationalization Programmer's Guide

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.