PO-DEBCONF(7) po-debconf PO-DEBCONF(7)
NAME
po-debconf - introduction
DESCRIPTION
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
translation.
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
o Translations are not stored along with the original (as it was too
often the case with the old system), which allows detection of out-
dated translations.
o 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.
o It is based internally on "intltool" (GNOME's answer to i18n diffi-
culties), 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.
o 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
problems ;).
o 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
just fine.
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 deb-
conf-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 trans-
lated.
- Creates debian/po/POTFILES.in
This file contains the list of master templates, and is used by
debconf-updatepo.
- 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
below).
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, tem-
plates.xx)
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 "deb-
helper", your package should build-depend directly on "po-debconf".
d. Make sure that your debian/rules file generates the localized tem-
plates 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 lan-
guage. In this case, you may contact the translator to solve this
issue, or ask for help on debian-i18n AT lists.org. Remove
".unknown" suffixes when encoding is fixed. (Most of the time,
steps b and c above will be enough if you use "dh_installdebconf")
UPDATE TEMPLATES
Every time you change the templates in English, PO files have to be
updated too. For that, simply call the following command without argu-
ments:
$ debconf-updatepo
Be careful, if the debian/po/POTFILES.in file was altered anyhow, this
command may fail, and you would be on your own to fix the situation!
You may want to hack debian/rules in order to update PO files automagi-
cally. The safest solution is to let this script run by the "clean"
target to ensure that debian/po/templates.pot and all PO files are up-
to-date in the source package.
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 automati-
cally using the dh_installdebconf script (make sure to have a ver-
sionned build dependency against "debhelper (>= 4.1.16)").
To do that manually, you'll have to merge the templates and the trans-
lations at compile time (and to have a build depend against "po-deb-
conf") 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 lan-
guages. 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 "deb-
conf-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
again.
NEW MASTER TEMPLATES
The new templates file source format is almost identical to one of dis-
tributed templates files, but translatable fields are prepended with an
underscore. Example:
Template: debconf/frontend
Type: select
_Choices: Dialog, Readline, Gnome, Editor, Noninteractive
Default: Dialog
_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 sepa-
rated 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
not significant.
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-deb-
conf" 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 con-
tain any colon, there is no need to add a versioned build dependency
against "po-debconf". An example can be found in the following sec-
tion.
CAVEATS
o "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 "deb-
conf" will ignore these fields, and English text is displayed. See
po2debconf(1) to know how to change encoding and output format.
o 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 spe-
cial 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;
o Spacing is not handled exactly the same way by "po-debconf" and "deb-
conf-utils"; with the latter, paragraphs are reformatted when updat-
ing 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 tem-
plates 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 tem-
plates to "po-debconf" format, unless you randomly change spaces in
master templates files, which will be painful for translators.
o Normally the Default: field must not be translated when template type
is Select or Multiselect. Under rare circumstances (e.g. when select-
ing 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.
Template: geneweb/lang
Type: select
__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; yuu 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:
#. DefaultChoice
msgid ""
"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)]"
msgstr ""
"Swedish"
Plain comments in templates files are less error prone and are
encouraged.
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 main-
tainer 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.
SEE ALSO
debconf-gettextize(1), debconf-updatepo(1), debconf2pot(1),
dh_installdebconf(1), po2debconf(1),
AUTHORS
Martin Quinson <Martin.Quinson AT ens-lyon.fr>
Denis Barbier <barbier AT linuxfr.org>
2005-04-08 PO-DEBCONF(7)
Huschi als Linux-Admin