Bug#655153: Trivial unfuzzy: please document the easy way

[David Prévot <taffit@debian.org>]

Source: developers-reference
Version: 3.4.6
Severity: wishlist
Tags: l10n patch

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

The developers reference currently documents two ways to unfuzzy
translations [1]. msguntypot offers an easy way to do the job, please
document it instead. The attached diff may be difficult to read, but you
can have a look at the built document [2] if you prefer.

1: http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#s6.5.2.3
2: http://people.debian.org/~taffit/developers-reference/best-pkging-practices.html#s6.5.2.3

Regards

David

- -- System Information:
Debian Release: wheezy/sid
  APT prefers unstable
  APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 3.1.0-1-amd64 (SMP w/1 CPU core)
Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iQIcBAEBCAAGBQJPCf4OAAoJELgqIXr9/gnyUJgQAJC5cCA/j6XskVILGPSP7ery
Shd+ibqjHCvh0hwhq2yIPooiJhrZB0lvxCVZB3wJ153fcATf5pzixWorRbUvseNw
LsVGocmssdG3dEleUtOHbjfPz3SvkMDJtno4EIl0Pat8o9kzQ3t/SdKbUrqwuSee
EagdwFZeIRoE7t12QRqFpXoqUzBh4djmcbgYWw27hOFBkm0RuNnWEF4N5XiUShUW
wgJPjArSguRW5ediJNr0/6aCoHVCqcOJlkvpFyz9DRnhd0s8pV9Ty4fWz0UJpplP
9X40zYi75P8l3+aVaToVYIQr5J4HO+39FdNxpzBKdC+5+cFtQaphCbwqfubv2uPR
Oza4wvdwJu0lUXklOlF8ZFYwezVxIjV92IRnIf7ExhXyLladwKRSmxmn85EAIPr7
fbjUFCDLs9FZvJ5G0LTTTEMWkWNfE9brh1X0EKPLx/UYX00MF/VIJ+kDmODvVtW0
CveRTVTIxZNF/w3MPcaAQOaAFZASHc00ki2uYshB3zFJ+/JWw9d6sazF8X+fv47o
TXHob+f84pYbPk4gjdGG7Z3N80qyhjvqzAxznElnDu6podloH3wS+tHym2+Kanpe
8Nil5LMPTmyrJoqTyPi0zWs72iXCDRZrYs3u2crCr+zjDPK/QBZN8GoN5DWTpePu
TFBP1MwqecxIgYIcSwfP
=Q0YY
-----END PGP SIGNATURE-----

Index: best-pkging-practices.dbk
===================================================================
--- best-pkging-practices.dbk	(révision 9028)
+++ best-pkging-practices.dbk	(copie de travail)
@@ -830,129 +830,63 @@
 translator will send you an update.
 </para>
 <para>
-To <emphasis>unfuzzy</emphasis> translations, you can use two methods. The first
-method does <emphasis>preventive</emphasis> search and replace actions in the
-PO files. The latter uses <command>gettext</command> utilities to <emphasis>unfuzzy</emphasis>
-strings.
+To <emphasis>unfuzzy</emphasis> translations, you can use
+<command>msguntypot</command> (part of the <systemitem
+role="package">po4a</systemitem> package).
 </para>
-<para>
-<emphasis>Preventive unfuzzy</emphasis> method:
-</para>
 <orderedlist numeration="arabic">
 <listitem>
 <para>
-Try finding a complete translation file <emphasis role="strong">before</emphasis>
-the change:
+Regenerate the POT and PO files.
 </para>
-<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done</programlisting>
-<para>
-The file only showing <emphasis>translated</emphasis> items will be used
-as the reference file. If there is none (which should not happen if you take
-care to properly interact with translators), you should use the file
-with the most translated strings.
-</para>
+<programlisting>debconf-updatepo</programlisting>
 </listitem>
 <listitem>
 <para>
-Identify the needed change. In this example, let's assume the change is about
-fixing a typo in the word <literal>typo</literal> which was inadvertently
-written as <literal>tpyo</literal>. Therefore, the change is
-<command>s/tpyo/typo</command>.
+Make a copy of the POT file.
 </para>
+<programlisting>cp templates.pot templates.pot.orig</programlisting>
 </listitem>
 <listitem>
 <para>
-Check that this change is only applied to the place where you really intend
-to make it and <emphasis role="strong">not</emphasis> in any other place
-where the original string is appropriate. This specifically applies to
-change in punctuation, for instance.
+Make a copy of all the PO files.
 </para>
+<programlisting>mkdir po_fridge; cp *.po po_fridge</programlisting>
 </listitem>
 <listitem>
 <para>
-Modify all PO files by using <command>sed</command>. The use of that command
-is recommended over any text editor to guarantee that the files encoding will
-not be broken by the edit action:
+Change the debconf template files to fix the typos.
 </para>
-<programlisting>
-cd debian/po
-for i in *.po; do sed -i 's/tpyo/typo/g' $i; done
-</programlisting>
 </listitem>
 <listitem>
 <para>
-Change the debconf template file to fix the typo.
+Regenerate the POT and PO files (again).
 </para>
-</listitem>
-<listitem>
+<programlisting>debconf-updatepo</programlisting>
 <para>
-Run <command>debconf-updatepo</command>.
+At this point, the typo fix fuzzied all the translations, and this
+unfortunate change is the only one between the PO files of your main
+directory and the one from the fridge. Here is how to solve this.
 </para>
 </listitem>
 <listitem>
 <para>
-Check the <filename>foo.po</filename> reference file. Its statistics should
-not be changed:
+Discard fuzzy translation, restore the ones from the fridge.
 </para>
-<programlisting>
-msgfmt -o /dev/null --statistics debian/po/foo.po
-</programlisting>
+<programlisting>cp po_fridge/*.po .</programlisting>
 </listitem>
 <listitem>
 <para>
-If the file's statistics changed, you did something wrong. Try again
-or ask for help on the &email-debian-i18n; mailing list.
+Manually merge the PO files with the new POT file, but taking the useless fuzzy into account.
 </para>
+<programlisting>msguntypot -o templates.pot.orig -n templates.pot *.po</programlisting>
 </listitem>
-</orderedlist>
-<para>
-Gettext utilities method:
-</para>
-<orderedlist numeration="arabic">
 <listitem>
-<para>
-Put all incomplete PO files out of the way.  You can check the completeness by
-using (needs the <systemitem role="package">gettext</systemitem> package
-installed):
+<para>  
+Clean up.
 </para>
-<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done</programlisting>
+<programlisting>rm -rf templates.pot.orig po_fridge</programlisting>
 </listitem>
-<listitem>
-<para>
-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.
-</para>
-</listitem>
-<listitem>
-<para>
-Now <emphasis role="strong">and now only</emphasis>, modify the template for
-the typos and check again that translation are not impacted (typos, spelling
-errors, sometimes typographical corrections are usually OK).
-</para>
-</listitem>
-<listitem>
-<para>
-Run <command>debconf-updatepo</command>.  This will fuzzy all strings you
-modified in translations.  You can see this by running the above again.
-</para>
-</listitem>
-<listitem>
-<para>
-Use the following command:
-</para>
-<programlisting>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</programlisting>
-</listitem>
-<listitem>
-<para>
-Move back to <filename>debian/po</filename> the files which showed fuzzy strings in the first step.
-</para>
-</listitem>
-<listitem>
-<para>
-Run <command>debconf-updatepo</command> again.
-</para>
-</listitem>
 </orderedlist>
 </section>