Provided by: po-debconf_0.9.2_all bug

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

       · Translations are not stored along with the original (as it was too
         often the case with the old system), which allows detection of
         outdated translations.

       · 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
         problems ;).

       · 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
       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
           translated.

       - 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,
          templates.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
          "debhelper", your package should build-depend directly on
          "po-debconf".

       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 debian-i18n@lists.debian.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

       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:

         $ debconf-updatepo

       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
          generated

       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
       again.

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:

         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
       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
       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-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.

CAVEATS

       · "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.

           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; 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:

           #. 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
       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.

SEE ALSO

       debconf-gettextize(1), debconf-updatepo(1), debconf2pot(1),
       dh_installdebconf(1), po2debconf(1),

AUTHORS

         Martin Quinson <Martin.Quinson@ens-lyon.fr>
         Denis Barbier <barbier@linuxfr.org>

                                  2005-12-22                     PO-DEBCONF(7)