Provided by: po-debconf_0.9.2_all
po-debconf - introduction
The goal of "debconf" was to make package configuration user-friendly.
In order to achieve this, it is important to ensure that users will get
the question in their own language. A system (called "debconf-utils"
in this document) was therefore designed to allow debconf templates
But this system had some drawbacks, and the need of a new solution
raised. "po-debconf" tries to solve these problems using some ideas
which proved to be useful in the context of messages translation.
ADVANTAGES OF THIS SYSTEM
· Translations are not stored along with the original (as it was too
often the case with the old system), which allows detection of
· Translations are stored in separate files from each other. This means
that translators for two different languages can update their work at
the same time without headaches for the maintainer. Moreover, one
translator cannot break the encoding of the other languages.
· It is based internally on "intltool" (GNOME’s answer to i18n
difficulties), which is itself based on "gettext" (but "po-debconf"
offers a very simple interface so that you don’t need to understand
its internals). That way, we do not have to re-implement the wheel,
and because of their wide use, we believe that these tools are more
or less bug free.
· Nothing changed for the end-user (beside the fact translations will
hopefully be better maintained :). The templates file distributed in
the binary package is exactly the same (only without the encoding
· No need for translators to learn a new file syntax and their favorite
po file editor (like emacs’po mode, kbabel or gtranslator) will work
In short, "po-debconf" is a system to ease the work of translators and
the inclusion of their work in "debconf" without changing what
shouldn’t be changed.
CONVERTING YOUR PACKAGE TO THIS SYSTEM
To convert your existing debconf templates and translations, call
debconf-gettextize from the toplevel directory with master templates
names as argument. Example:
$ debconf-gettextize debian/foo.templates debian/bar.templates
This command performs the following tasks:
- Creates debian/po/xx.po files
Here xx is a language code in which one of these files is
- Creates debian/po/POTFILES.in
This file contains the list of master templates, and is used by
- Adds a ".old" suffix to templates
In this example, foo.templates and bar.templates are renamed with a
".old" suffix, and new master files overwrite these files (see
In order to finish the conversion, you must:
a. Check that in the new templates files, the name of all translatable
fields (and only these ones) are prefixed with an underscore "_"
(see "New master templates" below).
b. Remove obsolete files: master.old and localized templates (ie,
c. Add "debhelper (>= 4.1.16)" to Build-Depends or Build-Depends-Indep
in debian/control to use dh_installdebconf. If you don’t use
"debhelper", your package should build-depend directly on
d. Make sure that your debian/rules file generates the localized
templates file, either via dh_installdebconf or po2debconf.
e. If debian/po/*.po.unknown files were generated, it means that the
script failed to determine automatically the encoding of this
language. In this case, you may contact the translator to solve
this issue, or ask for help on email@example.com. Remove
".unknown" suffixes when encoding is fixed. (Most of the time,
steps b and c above will be enough if you use dh_installdebconf)
In order to help translators, PO files in your package should always be
up-to-date, otherwise they may lose their time with unused strings.
For that, simply call the following command without arguments:
You should run this command every time you change templates in English,
but also when you receive new or updated translations, because
translators may have worked on an obsolete PO file.
If you rename, add or remove some templates files, remember also to
edit debian/po/POTFILES.in accordingly, otherwise English strings are
missing from PO files and will be displayed to users even if PO files
are fully translated.
The debconf-updatepo program is idempotent, it modifies PO files only
if their content has been updated. Thus the best solution to provide
up-to-date PO files in your source package is to call this command from
the "clean" target of the debian/rules file.
Please note that you need to run debconf-updatepo even if you use
dh_installdebconf. The latter calls po2debconf which in turn calls
debconf-updatepo if outdated files are detected, but this is not a good
solution for at least three reasons:
1. po2debconf relies on timestamps to detect outdated files, and may be
abused when using "pbuilder" or if an outdated translation has been
stored on disk after templates have been modified
2. dh_installdebconf is called long after ".diff.gz" file has been
3. because of the former points, po2debconf will be modified in future
versions to not run debconf-updatepo anymore.
MERGE TRANSLATIONS AND ORIGINAL
You have to make sure that when your package is compiled, translations
will get into the built package. You can do that manually, or
automatically using the dh_installdebconf script (make sure to have a
versionned build dependency against "debhelper (>= 4.1.16)").
To do that manually, you’ll have to merge the templates and the
translations at compile time (and to have a build depend against
"po-debconf") like this:
$ po2debconf debian/templates > debian/templates.merged
Then, you should install the resulting file in the right place:
$ cp debian/templates.merged debian/tmp/DEBIAN/templates
BE CAREFUL: the two files called templates in these two lines are not
the same at all. The first one contains only the English text, and
mark some fields to be translated while the second contains all
languages. That is to say that you CANNOT keep only the merged
templates, or you won’t be able to deal with translations as people
submit them to you.
By the way, this was one of the major drawback of the old
"debconf-utils" system. It was simply too tempting for developers to
keep only the merged templates, but it prevented translators to keep
track of the changes in English. Hopefully, since both versions of
this files don’t have the exact same syntax, people won’t do this error
NEW MASTER TEMPLATES
The new templates file source format is almost identical to one of
distributed templates files, but translatable fields are prepended with
an underscore. Example:
_Choices: Dialog, Readline, Gnome, Editor, Noninteractive
_Description: What interface should be used for configuring packages?
Packages that use debconf for configuration share a common look and
feel. You can select the type of user interface they use.
The dialog frontend is a full-screen, character based interface,
while the readline frontend uses a more traditional plain text
interface, and the gnome frontend is a modern X interface. The
editor frontend lets you configure things using your favorite text
editor. The noninteractive frontend never asks you any questions.
SPLITTING CHOICES LIST
Since "po-debconf" 0.6.0, localized fields may contain two leading
underscores. In this case, field value is supposed to be a comma
separated list of values, which are put in separate msgids. Thus if
the previous example did contain
__Choices: Dialog, Readline, Gnome, Editor, Noninteractive
there would be 5 different msgids. Note that spaces after commas are
Basically when a choices list never changes, "_Choices" is fine, but
otherwise "__Choices" will ease translator’s life.
PUTTING COMMENTS FOR TRANSLATORS
"Dpkg" maintainers decided that by convention lines beginning with a
number sign ("#") are comments in debian/control files, and
"po-debconf" follows this rule. Since "po-debconf" 0.8.0, such
comments are written into PO files, and can then contain valuable
informations for translators. Incidentally all previous "po-debconf"
versions ignore lines which do not contain a colon, thus if your
comments does not contain any colon, there is no need to add a
versioned build dependency against "po-debconf". An example can be
found in the following section.
· "Debconf" 1.2.0 recognizes fields in the form Name-lang.encoding,
e.g. "Description-de.ISO-8859-1" or "Choices-ru.KOI8-R". By default
po2debconf writes templates files in that new format. Older
"debconf" will ignore these fields, and English text is displayed.
See po2debconf(1) to know how to change encoding and output format.
· A given English string may have only one unique translation in a
given language. It is impossible to give two different translations,
depending on the context. To solve this issue, you have to add
special markups to the different occurrences of a given string to
make them different. (These markers will only be visible to
translators, and they will be removed from the string before being
displayed to user)
Such markers must be added to the end of the strings to translate,
they must start with "[ " (a left bracket followed by a space) and
end with "]" (right bracket), and may contain any character but
brackets or new lines. For example "[ blahblah]" is a valid marker
while "[ bla[bla]bla]" isn’t. For Perl regexp addicts, the markers
are recognized (and removed) using this rule:
$msg =~ s/\[\s[^\[\]]*\]$//s;
· Spacing is not handled exactly the same way by "po-debconf" and
"debconf-utils"; with the latter, paragraphs are reformatted when
updating and merging translations, so "debconf-utils" is very smart
and spaces are not considered as being part of strings when
determining fuzzy entries. (ie, the ones needing translator’s
attention because the original changed)
On the other hand "po-debconf" relies on "gettext" to detect fuzzy
entries, and it does not treat spaces as special characters. Thus
superfluous spaces must be removed at end of lines in master
templates files, or they will appear in PO and POT files.
For the same reason, debconf-gettextize can mark fuzzy text because
of mismatch with space characters, and translators have to manually
unfuzzy such strings. This only happens once when converting
templates to "po-debconf" format, unless you randomly change spaces
in master templates files, which will be painful for translators.
· Normally the Default: field must not be translated when template type
is Select or Multiselect. Under rare circumstances (e.g. when
selecting the default language for an application) localized values
may be meaningful.
The localized value must not be translated, but chosen from the
English values listed in the Choices field. The best way to achieve
this goal is to insert a comment in your templates file which will be
copied into PO files.
__Choices: Danish (da), Dutch (nl), English (en), Esperanto (eo)
# You must NOT translate this string, but you can change its value.
# The comment between brackets is used to distinguish this msgid
# from the one in the Choices list; you do not have to worry about
# them, and have to simply choose a msgstr among the English values
# listed in the Choices field above, e.g. msgstr "Dutch (nl)"
_Default: English (en)[ default language]
_Description: Geneweb default language
The default value also apears in the Choices field, and both have
different translations: the former is an untranslated value chosen
among Choices values, whereas the latter is a normal translation. As
"gettext" cannot hae two different translations for the same msgid,
both msgids must be different by using bracketed comments as
described in a previous subsection.
Prior to "po-debconf" 0.8.0, such comments were not available and
maintainers had to replace the _Default: field by _DefaultChoice: in
order to highlight such fields in PO files:
"English[ default: do not translate bracketed material, put your "
"own language here but UNTRANSLATED. If it is not in the list, "
"put English (without bracketed material)]"
Plain comments in templates files are less error prone and are
STATUS WEB PAGES
Translators can grab PO and POT files from
<http://www.debian.org/intl/l10n/po-debconf/> (or from mirrors). After
translating these files, they should submit their work to the
maintainer as bug report of severity minor with the patch tag.
The above pages are automatically updated when new packages are
uploaded. Only packages shipping debian/po/templates.pot and
debian/po/POTFILES.in files are considered, so you should make sure
your source package do provide them.
debconf-gettextize(1), debconf-updatepo(1), debconf2pot(1),
Martin Quinson <Martin.Quinson@ens-lyon.fr>
Denis Barbier <firstname.lastname@example.org>