6.5.4. Template fields specific style guide

6.5.4.1. Type field

No specific indication except: use the appropriate type by referring to the previous section.

6.5.4.2. Description field

Below are specific instructions for properly writing the Description (short and extended) depending on the template type.

6.5.4.2.1. String/password templates

• The short description is a prompt and not a title. Avoid question style prompts (IP Address?) in favour of opened prompts (IP address:). The use of colons is recommended.

• The extended description is a complement to the short description. In the extended part, explain what is being asked, rather than ask the same question again using longer words. Use complete sentences. Terse writing style is strongly discouraged.

6.5.4.2.2. Boolean templates

• The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).

• Again, please avoid referring to specific interface widgets. A common mistake for such templates is if you answer Yes-type constructions.

6.5.4.2.3. Select/Multiselect

• The short description is a prompt and not a title. Do not use useless “Please choose…” constructions. Users are clever enough to figure out they have to choose something… :)

• The extended description will complete the short description. It may refer to the available choices. It may also mention that the user may choose more than one of the available choices, if the template is a multiselect one (although the interface often makes this clear).

6.5.4.2.4. Notes

• The short description should be considered to be a title.

• The extended description is what will be displayed as a more detailed explanation of the note. Phrases, no terse writing style.

• Do not abuse debconf. Notes are the most common way to abuse debconf. As written in the debconf-devel manual page: it’s best to use them only for warning about very serious problems. The NEWS.Debian or README.Debian files are the appropriate location for a lot of notes. If, by reading this, you consider converting your Note type templates to entries in NEWS.Debian or README.Debian, please consider keeping existing translations for the future.

6.5.4.3. Choices field

If the Choices are likely to change often, please consider using the __Choices trick. This will split each individual choice into a single string, which will considerably help translators for doing their work.

6.5.4.4. Default field

If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick, documented in po-debconf 7.

This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.

Do not use an empty default field. If you don’t want to use default values, do not use Default at all.

If you use po-debconf (and you should; see Be kind to translators), consider making this field translatable, if you think it may be translated.

Example, taken from the geneweb package templates:

Template: geneweb/lang
Type: select
__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
# This is the default choice. Translators may put their own language here
# instead of the default.
# WARNING : you MUST use the ENGLISH NAME of your language
# For instance, the French translator will need to put French (fr) here.
_Default: English[ translators, please see comment in PO files]
_Description: Geneweb default language:

Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.

The comments are needed as the _Default trick is a bit confusing: the translators may put in their own choice.