Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
Unix Man page/Perldoc/Info page, English-Chinese Dictionary,
Chinese-English Dictionary
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. 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 o Translations are not stored along with the original (as it was too often the case with the old system), which allows detection of out- dated translations. o 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. o It is based internally on "intltool" (GNOME's answer to i18n diffi- culties), 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. o 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 ;). o 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 deb- conf-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 trans- lated. - 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, tem- plates.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 "deb- helper", your package should build-depend directly on "po-debconf". d. Make sure that your debian/rules file generates the localized tem- plates 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 lan- guage. In this case, you may contact the translator to solve this issue, or ask for help on debian-i18n AT lists.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 transla- tors 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 gen- erated 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 automati- cally using the dh_installdebconf script (make sure to have a ver- sionned 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 lan- guages. 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 "deb- conf-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 dis- tributed 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 sepa- rated 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-deb- conf" 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 con- tain any colon, there is no need to add a versioned build dependency against "po-debconf". An example can be found in the following sec- tion. 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 "deb- conf" 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 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 spe- cial 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 "deb- conf-utils"; with the latter, paragraphs are reformatted when updat- ing 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 tem- plates 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 tem- plates 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 select- ing 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 main- tainer 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 AT ens-lyon.fr> Denis Barbier <barbier AT linuxfr.org> 2005-12-20 PO-DEBCONF(7) |