Unix/Linux Go Back    


Linux 2.6 - man page for po-debconf (linux section 7)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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:

       - 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 in each template
	   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

UPDATE TEMPLATES
       In order to help translators, PO 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:

	 $ 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 way 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 generated

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 versioned 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/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 won't be able to deal with translations as people submit them to you.

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

   SPLITTING CHOICES LIST
       Since "po-debconf" 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

	 __Choices: Dialog, Readline, Gnome, Editor, Noninteractive

       there would be 5 different msgids.  Note that spaces after commas are not significant.

       When a choices list never changes, "_Choices" 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 "__Choices" will ease
       translator's life and is strongly recommended.

       Unfortunately if you decide to switch from "_Choices" to "__Choices", 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.

   PUTTING IN 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 information
       for translators.  Incidentally all previous "po-debconf" 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 "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
	    #flag:translate:3,4
	    __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
	    #flag:translate!:1,2
	    __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
	    #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}

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

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

	  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.

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

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

DEBUGGING
       You will find that debconf-loadtemplate 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

	 rm /tmp/{config,templates}.dat{,-old}
	 debconf-loadtemplate debian/templates
	 DEBIAN_PRIORITY=low debconf -freadline debian/config configure 28.0

       you will now need something like this instead:

	 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

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 "debconf" 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 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)

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

       o 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 ""
	   "Swedish"

	 Plain comments in templates files are less error prone and are encouraged.

STATUS WEB PAGES
       Statistics for "po-debconf" 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 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-<language>@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.

SEE ALSO
       debconf-gettextize(1), debconf-updatepo(1), dh_installdebconf(1), podebconf-report-po(1),
       po2debconf(1), debconf-devel(7).

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

					    2010-11-17				    PO-DEBCONF(7)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:16 PM.