6.5.2. General recommendations for authors and translators

6.5.2.1. Write correct English

Most Debian package maintainers are not native English speakers. So, writing properly phrased templates may not be easy for them.

Please use (and abuse) debian-l10n-english@lists.debian.org mailing list. Have your templates proofread.

Badly written templates give a poor image of your package, of your work… or even of Debian itself.

Avoid technical jargon as much as possible. If some terms sound common to you, they may be impossible to understand for others. If you cannot avoid them, try to explain them (use the extended description). When doing so, try to balance between verbosity and simplicity.

6.5.2.2. Be kind to translators

Debconf templates may be translated. Debconf, along with its sister package po-debconf, offers a simple framework for getting templates translated by translation teams or even individuals.

Please use gettext-based templates. Install po-debconf on your development system and read its documentation (man po-debconf is a good start).

Avoid changing templates too often. Changing template text induces more work for translators, which will get their translation fuzzied. A fuzzy translation is a string for which the original changed since it was translated, therefore requiring some update by a translator to be usable. When changes are small enough, the original translation is kept in PO files but marked as fuzzy.

If you plan to do changes to your original templates, please use the notification system provided with the po-debconf package, namely the podebconf-report-po, to contact translators. Most active translators are very responsive and getting their work included along with your modified templates will save you additional uploads. If you use gettext-based templates, the translator’s name and e-mail addresses are mentioned in the PO files headers and will be used by podebconf-report-po.

A recommended use of that utility is:

  1. cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"

This command will first synchronize the PO and POT files in debian/po with the template files listed in debian/po/POTFILES.in. Then, it will send a call for new translations, in the debian-i18n@lists.debian.org mailing list. Finally, it will also send a call for translation updates to the language team (mentioned in the Language-Team field of each PO file) as well as the last translator (mentioned in Last-translator).

Giving a deadline to translators is always appreciated, so that they can organize their work. Please remember that some translation teams have a formalized translate/review process and a delay lower than 10 days is considered as unreasonable. A shorter delay puts too much pressure on translation teams and should be kept for very minor changes.

If in doubt, you may also contact the translation team for a given language (debian-l10n-xxxxx@lists.debian.org), or the debian-i18n@lists.debian.org mailing list.

6.5.2.3. Unfuzzy complete translations when correcting typos and spelling

When the text of a debconf template is corrected and you are sure that the change does not affect translations, please be kind to translators and unfuzzy their translations.

If you don’t do so, the whole template will not be translated as long as a translator will send you an update.

To unfuzzy translations, you can use msguntypot (part of the po4a package).

  1. Regenerate the POT and PO files.

    1. debconf-updatepo

  2. Make a copy of the POT file.

    1. cp templates.pot templates.pot.orig

  3. Make a copy of all the PO files.

    1. mkdir po_fridge; cp *.po po_fridge

  4. Change the debconf template files to fix the typos.

  5. Regenerate the POT and PO files (again).

    1. debconf-updatepo

    At this point, the typo fix fuzzied all the translations, and this unfortunate change is the only one between the PO files of your main directory and the one from the fridge. Here is how to solve this.

  6. Discard fuzzy translation, restore the ones from the fridge.

    1. cp po_fridge/*.po .

  7. Manually merge the PO files with the new POT file, but taking the useless fuzzy into account.

    1. msguntypot -o templates.pot.orig -n templates.pot *.po

  8. Clean up.

    1. rm -rf templates.pot.orig po_fridge

6.5.2.4. Do not make assumptions about interfaces

Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes… have no meaning for users of graphical interfaces that use checkboxes for boolean questions.

String templates should also avoid mentioning the default values in their description. First, because this is redundant with the values seen by the users. Also, because these default values may be different from the maintainer choices (for instance, when the debconf database was preseeded).

More generally speaking, try to avoid referring to user actions. Just give facts.

6.5.2.5. Do not use first person

You should avoid the use of first person (I will do this… or We recommend…). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if … instead of This can be enabled if….

6.5.2.6. Be gender neutral

As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like “maintainer”) whose gender is unknown. Instead, you should use the plural form (singular they).