Bug#309502: developers-reference: Additional information for the debconf templates style guide part and debconf l10n handling
Package: developers-reference
Version: 3.3.6
Severity: wishlist
Tags: patch
Back in March, Andreas Barth suggested me to propose some additional
information about the recommended practices to properly handle changes in
debconf templates when they're about spelling errors or typo corrections,
especially how to deal with translations.
This came after a thread in debian-i18n where I pointed a few methods to
handle this nicely for translators.
Later, in #308234, Joey Hess made some comments about the write style of
some templates in a package, recommending to avoid referring to debconf
interfaces in templates wording. This also seemed to be a nice addition to
make to the chapter about debconf in the DR.
Please find attached a patch which adds this information. I also defined a
new entity for the debian-i18n mailing list and made the few existing
references to it use that entity.
-- System Information:
Debian Release: 3.1
APT prefers unstable
APT policy: (500, 'unstable'), (500, 'testing')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/bash
Kernel: Linux 2.6.8-2-686
Locale: LANG=C, LC_CTYPE=C (charmap=ANSI_X3.4-1968)
-- no debconf information
diff -Nru manuals.sgml.ori/developers-reference/common.ent manuals.sgml/developers-reference/common.ent
--- manuals.sgml.ori/developers-reference/common.ent 2005-05-13 23:29:16.775936670 +0200
+++ manuals.sgml/developers-reference/common.ent 2005-05-13 23:31:10.640776699 +0200
@@ -137,6 +137,7 @@
<!ENTITY email-debian-devel-announce "<email>debian-devel-announce@&lists-host;</email>">
<!ENTITY email-debian-devel-changes "<email>debian-devel-changes@lists.debian.org</email>">
<!ENTITY email-debian-devel-req "<email>debian-devel-REQUEST@&lists-host;</email>">
+<!ENTITY email-debian-i18n "<email>debian-i18n@&lists-host;</email>">
<!ENTITY email-debian-mentors "<email>debian-mentors@&lists-host;</email>">
<!ENTITY email-debian-private "<email>debian-private@&lists-host;</email>">
<!ENTITY email-debian-project "<email>debian-project@&lists-host;</email>">
diff -Nru manuals.sgml.ori/developers-reference/developers-reference.sgml manuals.sgml/developers-reference/developers-reference.sgml
--- manuals.sgml.ori/developers-reference/developers-reference.sgml 2005-05-13 23:29:17.045905468 +0200
+++ manuals.sgml/developers-reference/developers-reference.sgml 2005-05-13 23:36:59.000514894 +0200
@@ -4092,7 +4092,7 @@
Most Debian package maintainers are not native English speakers. So,
writing properly phrased templates may not be easy for them.
<p>
-Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+Please use (and abuse) &email-debian-l10n-english; mailing
list. Have your templates proofread.
<p>
Badly written templates give a poor image of your package, of your
@@ -4106,10 +4106,10 @@
<sect2>Be kind to translators
<p>
Debconf templates may be translated. Debconf, along with its sister
-package po-debconf offers a simple framework for getting
+package <prgn>po-debconf</prgn> offers a simple framework for getting
templates translated by translation teams or even individuals.
<p>
-Please use gettext-based templates. Install po-debconf on your
+Please use gettext-based templates. Install <package>po-debconf</package> on your
development system and read its documentation ("man po-debconf" is a
good start).
<p>
@@ -4122,10 +4122,57 @@
translator's name and e-mail addresses are mentioned in the po files
headers.
<p>
+The use of the <prgn>podebconf-report-po</prgn> from the
+po-debconf package is highly recommended to warn translators which
+have incomplete translations and request them for updates.
+ <p>
If in doubt, you may also contact the translation team for a given
language (debian-l10n-xxxxx@lists.debian.org), or the
-debian-i18n@lists.debian.org mailing list.
-
+&email-debian-i18n; mailing list.
+ <p>
+Calls for translations posted to
+&email-debian-i18n; with the <file>debian/po/templates.pot</file> file
+attached or referenced in a URL are encouraged. Be sure to mentions in
+these calls for new translations which languages you have existing
+translations for, in order to avoid duplicate work.
+ <sect2>Unfuzzy complete translations when correcting typos and spelling
+ <p>
+
+When the text of a debconf template is corrected and you are
+<strong>sure</strong> that the change does <strong>not</strong> affect
+translations, please be kind to translators and unfuzzy their
+translations.
+ <p>
+If you don't do so, the whole template will not be translated as long
+as a translator will send you an update.
+ <p>
+To <strong>unfuzzy</strong> translations, you can proceed the following way:
+ <enumlist>
+ <item>
+Put all incomplete PO files out of the way. You can check the
+completeness by using (needs the <package>gettext</package> package installed):
+<example>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done</example>
+ <item>
+move all files which report either fuzzy strings to a temporary
+place. Files which report no fuzzy strings (only translated and
+untranslated) will be kept in place.
+ <item>
+now <strong>and now only</strong>, modify the template for the typos
+and check again that translation are not impacted (typos, spelling
+errors, sometimes typographical corrections are usually OK)
+ <item>
+run <prgn>debconf-updatepo</prgn>. This will fuzzy all strings
+you modified in translations. You can see this by running the above
+again
+ <item>
+use the following command:
+<example>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</example>
+ <item>
+move back to debian/po the files which showed fuzzy strings in the first step
+ <item>
+run <prgn>debconf-updatepo</prgn> again
+ </enumlist>
<sect2>Do not make assumptions about interfaces
<p>
Templates text should not make reference to widgets belonging to some
@@ -4133,6 +4180,12 @@
meaning for users of graphical interfaces which use checkboxes for
boolean questions.
<p>
+String templates should also avoid mentioning the default values in
+their description. First, because this is redundant with the values
+seen by the users. Also, because these default values may be different
+from the maintainer choices (for instance, when the debconf database
+was preseeded).
+ <p>
More generally speaking, try to avoid referring to user actions.
Just give facts.
diff -Nru manuals.sgml.ori/developers-reference/dynamic.ent manuals.sgml/developers-reference/dynamic.ent
--- manuals.sgml.ori/developers-reference/dynamic.ent 1970-01-01 01:00:00.000000000 +0100
+++ manuals.sgml/developers-reference/dynamic.ent 2005-05-13 23:33:03.556726396 +0200
@@ -0,0 +1 @@
+<!entity % htmltext "IGNORE">
Reply to: