.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PO-DEBCONF 7"
.TH PO-DEBCONF 7 "2018-11-20" "" "po-debconf"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
po\-debconf \- introduction
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The goal of \f(CW\*(C`debconf\*(C'\fR 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.  Translators need a framework to easily
work on translations without having to track package development;
\&\f(CW\*(C`po\-debconf\*(C'\fR was designed to be able to work with standard \f(CW\*(C`gettext\*(C'\fR
tools when translating debconf templates files.
.SH "ADDING I18N SUPPORT TO DEBCONF TEMPLATES FILES"
.IX Header "ADDING I18N SUPPORT TO DEBCONF TEMPLATES FILES"
If you are adding debconf support to your package, you have written
a templates file containing English text.  To add proper i18n support
into your package, you need to:
.IP "\- Create \fIdebian/po/POTFILES.in\fR" 4
.IX Item "- Create debian/po/POTFILES.in"
This file contains the list of master templates.  It typically contains a
single line:
.Sp
.Vb 1
\&  [type: gettext/rfc822deb] templates
.Ve
.Sp
Paths are relative to the parent directory.
.IP "\- Prepend an underscore before translatable fields in each template" 4
.IX Item "- Prepend an underscore before translatable fields in each template"
Normally \f(CW\*(C`Description\*(C'\fR, \f(CW\*(C`Choices\*(C'\fR and sometimes \f(CW\*(C`Default\*(C'\fR fields can be translated.
.IP "\- Run \fBdebconf-updatepo\fR" 4
.IX Item "- Run debconf-updatepo"
This will create the \fIdebian/po/templates.pot\fR file that translators will translate
into their language.
.ie n .IP "\- Add a build dependency on ""po\-debconf"" in \fIdebian/control\fR" 4
.el .IP "\- Add a build dependency on \f(CWpo\-debconf\fR in \fIdebian/control\fR" 4
.IX Item "- Add a build dependency on po-debconf in debian/control"
.SH "UPDATE TEMPLATES"
.IX Header "UPDATE TEMPLATES"
In order to help translators, \s-1PO\s0 files in your package should always
be up-to-date, otherwise they may waste their time translating unused strings.
For that, simply call the following command without arguments:
.PP
.Vb 1
\&  $ debconf\-updatepo
.Ve
.PP
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 \s-1PO\s0 file.
.PP
If you rename, add or remove some templates files, remember also to
edit \fIdebian/po/POTFILES.in\fR accordingly, otherwise English strings 
are missing from \s-1PO\s0 files and will be displayed to users even if \s-1PO\s0
files are fully translated.
.PP
The \fBdebconf-updatepo\fR program is idempotent, it modifies \s-1PO\s0 files only
if their content has been updated.  Thus the best way to provide
up-to-date \s-1PO\s0 files in your source package is to call this command from
the \f(CW\*(C`clean\*(C'\fR target of the \fIdebian/rules\fR file.
.PP
Please note that you need to run \fBdebconf-updatepo\fR even if you use
\&\fBdh_installdebconf\fR.  The latter calls \fBpo2debconf\fR which used to
call \fBdebconf-updatepo\fR if outdated files were detected, but this
is no more the case because it was not a good solution for at least
two reasons:
.IP "1." 3
\&\fBpo2debconf\fR relied on timestamps to detect outdated files, and may
be abused when using \f(CW\*(C`pbuilder\*(C'\fR or if an outdated translation has
been stored on disk after templates have been modified
.IP "2." 3
\&\fBdh_installdebconf\fR is called long after \f(CW\*(C`.diff.gz\*(C'\fR file has been
generated
.SH "MERGE TRANSLATIONS AND ORIGINAL"
.IX Header "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 \fBdh_installdebconf\fR script (make sure to have a
versioned build dependency against \f(CW\*(C`debhelper (>= 4.1.16)\*(C'\fR).
.PP
To do that manually, you'll have to merge the templates and the
translations at compile time (and to have a build depend against
\&\f(CW\*(C`po\-debconf\*(C'\fR) like this:
.PP
.Vb 1
\&  $ po2debconf debian/templates > debian/tmp/DEBIAN/templates
.Ve
.PP
\&\fB\s-1BE CAREFUL\s0\fR: the two files called \fItemplates\fR are not the same at all.  The
first one contains only the English text, with marks to denote
some fields to be translated
while the second contains all languages.  That is to say that you \s-1CANNOT\s0 keep
only the merged templates, or you won't be able to deal with translations as
people submit them to you.
.SH "NEW MASTER TEMPLATES"
.IX Header "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:
.PP
.Vb 10
\&  Template: debconf/frontend
\&  Type: select
\&  _Choices: Dialog, Readline, Gnome, Editor, Noninteractive
\&  Default: Dialog
\&  _Description: Interface to use 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.
.Ve
.SS "\s-1SPLITTING CHOICES LIST\s0"
.IX Subsection "SPLITTING CHOICES LIST"
Since \f(CW\*(C`po\-debconf\*(C'\fR 0.6.0, localized fields may contain two leading
underscores.  In this case, the 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
.PP
.Vb 1
\&  _\|_Choices: Dialog, Readline, Gnome, Editor, Noninteractive
.Ve
.PP
there would be 5 different msgids.  Note that spaces after commas are
not significant.
.PP
When a choices list never changes, \f(CW\*(C`_Choices\*(C'\fR may be considered fine.
However, splitting such lists may help avoiding frequent mistakes in
translations such as omitting a choice or using non-standard commas.
For such reasons, the use of \f(CW\*(C`_\|_Choices\*(C'\fR will ease translator's life and
is strongly recommended.
.PP
Unfortunately if you decide to switch from \f(CW\*(C`_Choices\*(C'\fR to \f(CW\*(C`_\|_Choices\*(C'\fR, all translations
become fuzzy.  Here is an explanation to make this change without translation
loss (it requires \f(CW\*(C`po\-debconf\*(C'\fR >= 1.0).  Suppose that we want to switch the
previous example to \f(CW\*(C`_\|_Choices\*(C'\fR.  You copy the \fItemplates\fR file into a
temporary file.
.PP
.Vb 1
\&  $ cp debian/templates debian/foo
.Ve
.PP
Edit \fIdebian/foo\fR and keep only \f(CW\*(C`Template\*(C'\fR, \f(CW\*(C`Type\*(C'\fR and \f(CW\*(C`_Choices\*(C'\fR
fields, which are in this example
.PP
.Vb 3
\&  Template: debconf/frontend
\&  Type: select
\&  _Choices: Dialog, Readline, Gnome, Kde, Editor, Noninteractive
.Ve
.PP
Run \fBdebconf-gettextize\fR with \f(CW\*(C`\-\-merge\*(C'\fR and \f(CW\*(C`\-\-choices\*(C'\fR flags to build \s-1PO\s0 files
as if \f(CW\*(C`_\|_Choices\*(C'\fR was written, and merge these \s-1PO\s0 files to existing ones:
.PP
.Vb 1
\&  $ debconf\-gettextize \-\-merge \-\-choices debian/foo
.Ve
.PP
Eventually you have to remove \fIfoo\fR and manually edit \fIdebian/templates\fR to
replace \f(CW\*(C`_Choices\*(C'\fR by \f(CW\*(C`_\|_Choices\*(C'\fR before \fBdebconf-updatepo\fR is run.
.SS "\s-1PUTTING IN COMMENTS FOR TRANSLATORS\s0"
.IX Subsection "PUTTING IN COMMENTS FOR TRANSLATORS"
\&\f(CW\*(C`Dpkg\*(C'\fR maintainers decided that by convention lines beginning with
a number sign (\f(CW\*(C`#\*(C'\fR) are comments in \fIdebian/control\fR files, and \f(CW\*(C`po\-debconf\*(C'\fR
follows this rule.  Since \f(CW\*(C`po\-debconf\*(C'\fR 0.8.0, such comments are written
into \s-1PO\s0 files, and can then contain valuable information for
translators.  Incidentally all previous \f(CW\*(C`po\-debconf\*(C'\fR versions ignore
lines which do not contain a colon, thus if your comments does not
contain any colons, there is no need to add a versioned build dependency
against \f(CW\*(C`po\-debconf\*(C'\fR.  Here is an example:
.PP
.Vb 4
\&  Template: debconf/button\-yes
\&  Type: text
\&  # Translators, this text will appear on a button, so KEEP IT SHORT
\&  _Description: Yes
.Ve
.PP
Special comments have been introduced in \f(CW\*(C`po\-debconf\*(C'\fR 1.0 to deal with
strings which are composed of several items (as with \fIChoices\fR field) or
paragraphs (like \fIDescription\fR).  With these directives, developers have
a better control over what is exposed to translators.  They are in the
form \f(CW\*(C`#flag:\f(CIdirective\f(CW\*(C'\fR; directives are detailed below.
.IP "\fBtranslate:\fR\fIspec\fR, \fBtranslate!:\fR\fIspec\fR" 3
.IX Item "translate:spec, translate!:spec"
Mark only some items as translatable; \fIspec\fR is a comma separated list of numbers,
it specifies which strings will be printed into \s-1PO\s0 files.  Ranges can also be
defined via a minus sign (for instance \f(CW\*(C`2\-6\*(C'\fR), and a star (\f(CW\*(C`*\*(C'\fR) means all
strings.  For instance, with
.Sp
.Vb 5
\&  Template: partman\-basicfilesystems/fat_mountpoint
\&  Type: select
\&  #flag:translate:3,4
\&  _\|_Choices: /dos, /windows, Enter manually, Do not mount it
\&  _Description: Mount point for this partition:
.Ve
.Sp
\&\f(CW\*(C`Enter manually\*(C'\fR and \f(CW\*(C`Do not mount it\*(C'\fR will appear in \s-1PO\s0 files but not \f(CW\*(C`/dos\*(C'\fR
and \f(CW\*(C`/windows\*(C'\fR.  When an exclamation mark follows the \fBtranslate\fR keyword,
\&\fIspec\fR specifies which strings will be discarded from \s-1PO\s0 files, all other
strings are printed.  Previous example is similar to
.Sp
.Vb 5
\&  Template: partman\-basicfilesystems/fat_mountpoint
\&  Type: select
\&  #flag:translate!:1,2
\&  _\|_Choices: /dos, /windows, Enter manually, Do not mount it
\&  _Description: Mount point for this partition:
.Ve
.Sp
The same keyword can also be applied to the \fIDescription\fR field to make sure that
some strings are not translated.
.Sp
.Vb 8
\&  Template: partman\-crypto/options_missing
\&  Type: error
\&  #flag:translate!:3
\&  _Description: Required encryption options missing
\&   The encryption options for ${DEVICE} are incomplete. Please
\&   return to the partition menu and select all required options.
\&   .
\&   ${ITEMS}
.Ve
.Sp
But this is hazardous because context may be dropped from \s-1PO\s0 files, please add
comments in this case so that translators are not confused.
.IP "\fBcomment:\fR\fIspec\fR, \fBcomment!:\fR\fIspec\fR" 3
.IX Item "comment:spec, comment!:spec"
The comment just below this directive applies to the strings specified by
\&\fIspec\fR, which is defined above.  By default, a comment written before a
translatable field is printed along with all strings belonging to this
field.  (Note: with \f(CW\*(C`po\-debconf\*(C'\fR < 1.0, the comment was printed
only with the first string)
.Sp
.Vb 10
\&  Template: arcboot\-installer/prom\-variables
\&  Type: note
\&  # Translators, the 4th string of this description has been dropped
\&  # from PO files.  It contains shell commands and should not be
\&  # translated.
\&  #flag:comment:3
\&  # "Stop for Maintenance" should be left in English
\&  #flag:translate!:4
\&  _Description: Setting PROM variables for Arcboot
\&   If this is the first Linux installation on this machine, or if the
\&   hard drives have been repartitioned, some variables need to be set
\&   in the PROM before the system is able to boot normally.
\&   .
\&   At the end of this installation stage, the system will reboot.
\&   After this, enter the command monitor from the "Stop for
\&   Maintenance" option, and enter the following commands:
\&   .
\&      setenv OSLoader arcboot
\&      setenv OSLoadFilename Linux
\&   .
\&   You will only need to do this once.  Afterwards, enter the "boot"
\&   command or reboot the system to proceed to the next stage of the
\&   installation.
.Ve
.Sp
The example above has a comment without \f(CW\*(C`#flag:comment\*(C'\fR directive, where an implicit
\&\f(CW\*(C`#flag:comment:*\*(C'\fR is added.  This comment appears with all strings, but the
one about \fIStop for Maintenance\fR is printed only before the relevant string.
.IP "\fBpartial\fR" 3
.IX Item "partial"
This keyword tells \fBpo2debconf\fR to keep translated strings even if all strings
have not been translated.  Please use with caution, this keyword has been
introduced for very specific purposes.
.SS "\s-1GIVING NOTICES TO TRANSLATORS BEFORE UPLOADING\s0"
.IX Subsection "GIVING NOTICES TO TRANSLATORS BEFORE UPLOADING"
Usually translators notice on the status web pages (see below) that translations
are outdated, and send patches which will be included in future uploads.  But
developers are encouraged to ask maintainers of outdated translations for
an update before an upload,
for instance one week in advance.  A dedicated tool, \fBpodebconf-report-po\fR,
has been written for this purpose.  Do not hesitate to abuse it!
.SH "DEBUGGING"
.IX Header "DEBUGGING"
You will find that \fBdebconf-loadtemplate\fR will not accept a templates
file with i18n markups.  However, it will accept a merged file, so if
you have been debugging your debconf setup like this
.PP
.Vb 3
\&  rm /tmp/{config,templates}.dat{,\-old}
\&  debconf\-loadtemplate debian/templates
\&  DEBIAN_PRIORITY=low debconf \-freadline debian/config configure 28.0
.Ve
.PP
you will now need something like this instead:
.PP
.Vb 4
\&  po2debconf debian/templates > debian/tmp/DEBIAN/templates
\&  rm /tmp/{config,templates}.dat{,\-old}
\&  debconf\-loadtemplate debian/tmp/DEBIAN/templates
\&  DEBIAN_PRIORITY=low debconf \-freadline debian/config configure 28.0
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
.IP "\(bu" 2
\&\f(CW\*(C`Debconf\*(C'\fR 1.2.0 recognizes fields in the form \fIName\fR\-\fIlang\fR.\fIencoding\fR,
e.g. \f(CW\*(C`Description\-de.ISO\-8859\-1\*(C'\fR or \f(CW\*(C`Choices\-ru.KOI8\-R\*(C'\fR.  By default
\&\fBpo2debconf\fR writes templates files in that new format.  Older \f(CW\*(C`debconf\*(C'\fR
will ignore these fields, and English text is displayed.  See
\&\fBpo2debconf\fR\|(1) to know how to change encoding and output format.
.IP "\(bu" 2
A given English string may be given 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)
.Sp
Such markers must be added to the end of the strings to translate, they
must start with \f(CW\*(C`[ \*(C'\fR (a left bracket followed by a space) and end with
\&\f(CW\*(C`]\*(C'\fR (right bracket), and may contain any character but brackets or new
lines. For example \f(CW\*(C`[ blahblah]\*(C'\fR is a valid marker while
\&\f(CW\*(C`[ bla[bla]bla]\*(C'\fR isn't. For Perl regexp addicts, the markers are
recognized (and removed) using this rule:
.Sp
.Vb 1
\&  $msg =~ s/\e[\es[^\e[\e]]*\e]$//s;
.Ve
.IP "\(bu" 2
Spacing is not handled exactly the same way by \f(CW\*(C`po\-debconf\*(C'\fR and
\&\f(CW\*(C`debconf\-utils\*(C'\fR; with the latter, paragraphs are reformatted when updating
and merging translations, so \f(CW\*(C`debconf\-utils\*(C'\fR is very smart and spaces are
not considered as being part of strings when determining fuzzy entries.
(i.e., the ones needing translator's attention because the original
changed)
.Sp
On the other hand \f(CW\*(C`po\-debconf\*(C'\fR relies on \f(CW\*(C`gettext\*(C'\fR 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 \s-1PO\s0 and \s-1POT\s0 files.
.Sp
For the same reason, \fBdebconf-gettextize\fR can mark text fuzzy because of
mismatch with space characters, and translators have to manually unfuzzy
such strings.  This only happens once when converting templates to
\&\f(CW\*(C`po\-debconf\*(C'\fR format, unless you randomly change spaces in master templates
files, which will be painful for translators.
.IP "\(bu" 2
Normally the \fIDefault:\fR field must not be translated when template type is
\&\fBSelect\fR or \fBMultiselect\fR. Under rare circumstances (e.g. when
selecting the default language for an application) localized values may
be meaningful.
.Sp
The localized value must not be translated, but chosen from the English
values listed in the \fIChoices\fR field.  The best way to achieve this
goal is to insert a comment in your templates file which will be copied
into \s-1PO\s0 files.
.Sp
.Vb 10
\&  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
.Ve
.Sp
The default value also appears in the \fIChoices\fR field, and both have
different translations: the former is an untranslated value chosen
among \fIChoices\fR values, whereas the latter is a normal translation.
As \f(CW\*(C`gettext\*(C'\fR cannot have two different translations for the same
\&\fImsgid\fR, both \fImsgids\fR must be different by using bracketed comments
as described in a previous subsection.
.Sp
Prior to \f(CW\*(C`po\-debconf\*(C'\fR 0.8.0, such comments were not available and
maintainers had to replace the \fI_Default:\fR field by \fI_DefaultChoice:\fR
in order to highlight such fields in \s-1PO\s0 files:
.Sp
.Vb 7
\&  #. 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"
.Ve
.Sp
Plain comments in templates files are less error prone and are
encouraged.
.SH "STATUS WEB PAGES"
.IX Header "STATUS WEB PAGES"
Statistics for \f(CW\*(C`po\-debconf\*(C'\fR translations are available at
<http://www.debian.org/intl/l10n/po\-debconf/> (or from mirrors);
they are automatically updated when new packages are uploaded.
Only packages shipping \fIdebian/po/templates.pot\fR and
\&\fIdebian/po/POTFILES.in\fR files are considered, so you should make
sure your source package provides them.
.PP
Translators can grab \s-1PO\s0 and \s-1POT\s0 files from there, but they must
always get in touch with the previous translator (her mail address
can be found in the \s-1PO\s0 file) and/or their fellow translators on
debian\-l10n\-\fI<language>\fR\f(CW@lists\fR.debian.org (if such a list
does exist) to make sure that no one is currently working on the
same translation, and read current bugreports against the package
they are going to translate to see if a translation has already
been reported.
.PP
After translating these files, they should submit their work to the
maintainer as bug report of severity \fBwishlist\fR with the \fBpatch\fR tag.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebconf\-gettextize\fR\|(1),
\&\fBdebconf\-updatepo\fR\|(1),
\&\fBdh_installdebconf\fR\|(1),
\&\fBpodebconf\-report\-po\fR\|(1),
\&\fBpo2debconf\fR\|(1),
\&\fBdebconf\-devel\fR\|(7).
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 2
\&  Martin Quinson <Martin.Quinson@ens\-lyon.fr>
\&  Denis Barbier <barbier@linuxfr.org>
.Ve