Quick ?s
Cheat Sheets
Man Pages
The Lynx
PO-DEBCONF(7)			  po-debconf			 PO-DEBCONF(7)

       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.  Translators need a framework to
       easily work on translations without having to track down package
       development; "po-debconf" was designed to be able to work with standard
       "gettext" tools when translating 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:

       - Create debian/po/POTFILES.in
	   This file contains the list of master templates.  It typically
	   contains a single line:

	     [type: gettext/rfc822deb] templates

	   Paths are relative to the parent directory.

       - Prepend an underscore before translatable fields
	   Normally "Description", "Choices" and sometimes "Default" fields
	   can be translated.

       - Run debconf-updatepo
	   This will create the debian/po/templates.pot file that translators
	   will translate into their language.

       - Add a build dependency on "po-debconf" in debian/control

       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 used to call
       debconf-updatepo if outdated files were detected, but this is no more
       the case because it was not a good solution for at least two reasons:

       1. po2debconf relied 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

       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
       versioned build dependency against "debhelper (>= 4.1.16)").

       To do that manually, youll 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/tmp/DEBIAN/templates

       BE CAREFUL: the two files called templates 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 CANNOT keep only the merged templates, or you wont
       be able to deal with translations as people submit them to you.

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


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

       Unfortunately if you decide to switch between these two forms, all
       translations become fuzzy.  Here is an explanation to make this change
       without translation loss (it requires "po-debconf" >= 1.0).  Suppose
       that we want to switch the previous example to "__Choices".  You copy
       the templates file into a temporary file.

	 $ cp debian/templates debian/foo

       Edit debian/foo and keep only "Template", "Type" and "_Choices" fields,
       which are in this example

	 Template: debconf/frontend
	 Type: select
	 _Choices: Dialog, Readline, Gnome, Kde, Editor, Noninteractive

       Run debconf-gettextize with "--merge" and "--choices" flags to build PO
       files as if "__Choices" was written, and merge these PO files to
       existing ones:

	 $ debconf-gettextize --merge --choices debian/foo

       Eventually you have to remove foo and manually edit debian/templates to
       replace "_Choices" by "__Choices" before debconf-updatepo is run.


       "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".  Here is an example:

	 Template: debconf/button-yes
	 Type: text
	 # Translators, this text will appear on a button, so KEEP IT SHORT
	 _Description: Yes

       Special comments have been introduced in "po-debconf" 1.0 to deal with
       strings which are composed of several items (as with Choices field) or
       paragraphs (like Description).  With these directives, developers have
       a better control over what is exposed to translators.  They are in the
       form "#flag:directive"; directives are detailed below.

       translate:spec, translate!:spec
	  Mark only some items as translatable; spec is a comma separated list
	  of numbers, it specifies which strings will be printed into PO
	  files.  Ranges can also be defined via a minus sign (for instance
	  "2-6"), and a star ("*") means all strings.  For instance, with

	    Template: partman-basicfilesystems/fat_mountpoint
	    Type: select
	    __Choices: /dos, /windows, Enter manually, Do not mount it
	    _Description: Mount point for this partition:

	  "Enter manually" and "Do not mount it" will appear in PO files but
	  not "/dos" and "/windows".  When an exclamation mark follows the
	  translate keyword, spec specifies which strings will be discarded
	  from PO files, all other strings are printed.  Previous example is
	  similar to

	    Template: partman-basicfilesystems/fat_mountpoint
	    Type: select
	    __Choices: /dos, /windows, Enter manually, Do not mount it
	    _Description: Mount point for this partition:

	  The same keyword can also be applied to the Description field to
	  make sure that some strings are not translated.

	    Template: partman-crypto/options_missing
	    Type: error
	    _Description: Required encryption options missing
	     The encryption options for ${DEVICE} are incomplete. Please
	     return to the partition menu and select all required options.

	  But this is hazardous because context may be dropped from PO files,
	  please add comments in this case so that translators are not

       comment:spec, comment!:spec
	  The comment just below this directive applies to the strings
	  specified by spec, 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 "po-debconf" < 1.0,
	  the comment was printed only with the first string)

	    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.
	    # "Stop for Maintenance" should be left in English
	    _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

	  The example above has a comment without "#flag:comment" directive,
	  where an implicit "#flag:comment:*" is added.  This comment appears
	  with all strings, but the one about Stop for Maintenance is printed
	  only before the relevant string.

	  This keyword tells po2debconf 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.


       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, podebconf-report-po, has been
       written for this purpose.  Do not hesitate to abuse it!

	"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]" isnt. 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.  (i.e., the ones needing translators
	 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 text fuzzy 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 appears 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 have 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 ""

	 Plain comments in templates files are less error prone and are

       Statistics for "po-debconf" translations are available at
        (or from mirrors); they
       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
       provides them.

       Translators can grab PO and POT files from there, but they must always
       get in touch with the previous translator (her mail address can be
       found in the PO file) and/or their fellow translators on
       debian-l10n-@lists.debian.org (if such a list does exist) to
       make sure that noone 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.

       After translating these files, they should submit their work to the
       maintainer as bug report of severity wishlist with the patch tag.

       debconf-gettextize(1), debconf-updatepo(1), dh_installdebconf(1),
       podebconf-report-po(1).	po2debconf(1).

	 Martin Quinson 
	 Denis Barbier 

				  2008-06-13			 PO-DEBCONF(7)

Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:31 2009