po-debconf

po-debconf - introduction

The goal of CWdebconf 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; CWpo-debconf was designed to be able to work with standard CWgettext 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:

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

"- Normally CWDescription, CWChoices and sometimes CWDefault fields can be translated.

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

In order to help translators, \s-1PO\s0 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 \s-1PO\s0 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 \s-1PO\s0 files and will be displayed to users even if \s-1PO\s0 files are fully translated.

The debconf-updatepo program is idempotent, it modifies \s-1PO\s0 files only if their content has been updated. Thus the best solution to provide up-to-date \s-1PO\s0 files in your source package is to call this command from the CWclean 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 CWpbuilder or if an outdated translation has been stored on disk after templates have been modified

"2." dh_installdebconf is called long after CW.diff.gz file has been generated

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 CWdebhelper (>= 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 CWpo-debconf) like this:

$ po2debconf debian/templates > debian/tmp/DEBIAN/templates

\s-1BE\s0 \s-1CAREFUL\s0: the two files called templates 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 \s-1CANNOT\s0 keep only the merged templates, or you won't 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 CWpo-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, CW_Choices is fine, but otherwise CW__Choices will ease translator's 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 CWpo-debconf >= 1.0). Suppose that we want to switch the previous example to CW__Choices. You copy the templates file into a temporary file.

$ cp debian/templates debian/foo

Edit debian/foo and keep only CWTemplate, CWType and CW_Choices fields, which are in this example

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

Run debconf-gettextize with CW--merge and CW--choices flags to build \s-1PO\s0 files as if CW__Choices was written, and merge these \s-1PO\s0 files to existing ones:

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

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

CWDpkg maintainers decided that by convention lines beginning with a number sign (CW#) are comments in debian/control files, and CWpo-debconf follows this rule. Since CWpo-debconf 0.8.0, such comments are written into \s-1PO\s0 files, and can then contain valuable informations for translators. Incidentally all previous CWpo-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 CWpo-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 CWpo-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 CW#flag:CIdirectiveCW; directives are detailed below.

"translate:spec, Mark only some items as translatable; spec 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 CW2-6), and a star (CW*) 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: CWEnter manually and CWDo not mount it will appear in \s-1PO\s0 files but not CW/dos and CW/windows. When an exclamation mark follows the translate keyword, spec specifies which strings will be discarded from \s-1PO\s0 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 \s-1PO\s0 files, please add comments in this case so that translators are not confused.

"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 CWpo-debconf < 1.0, the comment was written 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 CW#flag:comment directive, an implicit CW#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.

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 send outdated files to translators 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!

"" CWDebconf 1.2.0 recognizes fields in the form Name-lang.encoding, e.g. CWDescription-de.ISO-8859-1 or CWChoices-ru.KOI8-R. By default po2debconf writes templates files in that new format. Older CWdebconf 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 CW[ (a left bracket followed by a space) and end with CW] (right bracket), and may contain any character but brackets or new lines. For example CW[ blahblah] is a valid marker while CW[ 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 CWpo-debconf and CWdebconf-utils; with the latter, paragraphs are reformatted when updating and merging translations, so CWdebconf-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 CWpo-debconf relies on CWgettext 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. 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 CWpo-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 \s-1PO\s0 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 CWgettext 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 CWpo-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 \s-1PO\s0 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.

Statistics for CWpo-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 do provide them.

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-<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 minor with the patch tag.

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