PO-DEBCONF(7)

📦
version 1.0.22 · 2 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so this is po-debconf(7) — literally the intro page, bestie. consider it your lil' welcome mat to the whole po-debconf situation. 🫶

✨ DESCRIPTION ✨

so the whole goal of debconf was to make package configuration actually user-friendly, right? and to do that, it's super important that users get the question in their own language. like, obviously. 🌍

but here's the thing — translators need a framework where they can just vibe and work on translations without having to track package development constantly (imagine tracking someone's dev branch like it's their finsta, exhausting). so po-debconf was designed to play nice with the standard gettext tools when you're translating debconf templates files. it's giving "built for the group project." 💅

🦋 ADDING I18N SUPPORT TO DEBCONF TEMPLATES FILES 🦋

so if you're adding debconf support to your package, you've already written a templates file with English text in it. cute! now to add proper i18n support into your package, you literally need to do these things:

  • Create debian/po/POTFILES.in this file holds the list of master templates. typically it's just one single line:
[type: gettext/rfc822deb] templates

and heads up — paths are relative to the parent directory. 📁

  • Prepend an underscore before translatable fields in each template normally the Description, Choices and sometimes Default fields are the ones that can be translated. that lil _ is the whole vibe. ✨
  • Run debconf-updatepo this creates the debian/po/templates.pot file, and that's the file translators will translate into their language. it's the blueprint, bestie.
  • Add a build dependency on po-debconf in debian/control no cap, don't skip this one.

🌸 UPDATE TEMPLATES 🌸

okay so to help translators out, the PO files in your package should always be up-to-date. otherwise they might waste their time translating strings that nobody even uses anymore, and that's just disrespectful to their time. 😭

to do that, simply call this command with no arguments:

$ debconf-updatepo

you should run this every time you change templates in English, and also when you receive new or updated translations — because translators may have been working on an obsolete PO file this whole time. rude awakening, but necessary. 🙈

if you rename, add or remove some templates files, remember to also edit debian/po/POTFILES.in accordingly! otherwise English strings are missing from the PO files and will get displayed to users even if the PO files are fully translated. like, fully translated and still showing English?? tragic.

good news tho: the debconf-updatepo program is idempotent — it only modifies PO files if their content has actually been updated. so the best way to keep up-to-date PO files in your source package is to call this command from the clean target of the debian/rules file. slay. 💅

🚨 please note: 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, the translations will actually get into the built package. you can do that manually, or automatically using the dh_installdebconf script — just make sure you have a versioned build dependency against debhelper (>= 4.1.16). 👑

to do it manually, you'll have to merge the templates and the translations at compile time (and 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. do not do this. i am begging. 😭

✨ NEW MASTER TEMPLATES ✨

okay so bestie, the new templates file source format is almost identical to one of those distributed templates files — except the translatable fields get an underscore booped onto the front. 💅 like this:

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 can carry two leading underscores. when that happens, the field value is supposed to be a comma separated list of values, and each one gets its very own separate msgid. so if that example above had instead said

__Choices: Dialog, Readline, Gnome, Editor, Noninteractive

you'd get 5 different msgids. ✨ note that spaces after commas? not significant, don't stress. 💖

when a choices list never changes, _Choices is honestly fine. but splitting those lists can help you dodge frequent translation mistakes like omitting a choice or using non-standard commas. so for those reasons, using __Choices makes a translator's life so much easier and it is strongly recommended. 👑

unfortunately 😭 if you decide to switch from _Choices to __Choices, all your translations go fuzzy. here's how to make that change without losing any translation (it needs po-debconf >= 1.0). say we wanna 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 the Template, Type and _Choices fields, which in this example are

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 those PO files into the existing ones:

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

eventually you have to remove foo and manually edit debian/templates to swap _Choices for __Choices before debconf-updatepo is run. 🫶

🎀 PUTTING IN COMMENTS FOR TRANSLATORS

so the Dpkg maintainers decided that, by convention, lines starting with a number sign (#) are comments in debian/control files, and po-debconf follows that rule. and since po-debconf 0.8.0, those comments get written into PO files, which means they can carry valuable info for translators. 💜 incidentally, all previous po-debconf versions ignore lines that don't contain a colon — so if your comments don't have any colons, there's no need to add a versioned build dependency against po-debconf. here's an example:

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

special comments got introduced in po-debconf 1.0 to deal with strings composed of several items (like a Choices field) or paragraphs (like Description). with these directives, developers get way better control over what's exposed to translators. they come 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, and it says which strings get printed into PO files. you can also define ranges with a minus sign (like 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 show up in PO files but /dos and /windows will not. 🦋 when an exclamation mark follows the translate keyword, spec says which strings get discarded from PO files, and all the other strings get printed. the previous example is basically the same as

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 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 bestie this is hazardous 😭 because context may get dropped from PO files. please add comments in this case so translators aren't left 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 gets printed along with all strings belonging to that 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 a #flag:comment directive, so an implicit #flag:comment:* gets added. that comment shows up 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 not all strings have been translated. please use with caution — this keyword was 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 then they send patches that get included in future uploads. but developers are encouraged to ask maintainers of outdated translations for an update before an upload — like, one week in advance, for instance. there's a dedicated tool for this: podebconf-report-po. do not hesitate to abuse it! 🔥

💀 DEBUGGING

you're gonna find that debconf-loadtemplate will not accept a templates file with i18n markups. no ma'am. but it will accept a merged file. so if you've 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

then you'll 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 💀

okay bestie, sit down, because this is the part where we talk about the ✨gotchas✨. ngl these are the things that will have you screaming at 3am if you don't read them. so like, read them.

  • "Debconf" 1.2.0 recognizes fields in the form Name-lang.encoding, like Description-de.ISO-8859-1 or Choices-ru.KOI8-R, fr fr. By default po2debconf writes templates files in that new format. But older "debconf" will literally just ignore these fields and English text gets displayed instead 😭. Wanna know how to change encoding and output format? Go check po2debconf(1), iykyk.
  • a given English string can only have ONE unique translation per language. Like, it is genuinely impossible to give two different translations depending on context — the system said no 💅. To solve this 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 — so the user never sees them, we promise 🫶.)

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. And for all my Perl regexp addicts out there 👑, 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", and this is where things get spicy. With debconf-utils, 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. So like, superfluous spaces must be removed at end of lines in master templates files, or they will appear in PO and POT files. no cap.

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. don't do that bestie. that's giving villain behaviour.

  • 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. (yes, the brackets again. they're iconic like that 🌈)

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. ✨ periodt.

🌈 STATUS WEB PAGES 🌈

Statistics for "po-debconf" translations are available at <http://www.debian.org/intl/l10n/po-debconf/> (or from mirrors, bestie, no stress) — 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 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. Like, communicate!! 🫶

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

🦋 SEE ALSO 🦋

👑 AUTHORS 👑

  • Martin Quinson <Martin.Quinson@ens-lyon.fr>
  • Denis Barbier <barbier@linuxfr.org>
this whole page is from the PO-DEBCONF(7) manual, dated 2025-12-07, and it was lowkey a whole journey 💖 go forth and translate, bestie, you ate 💅✨🎀
📦 where this page comes from