Re: Bug#474879: Proposed changes to section 6.2.2 about translation updates and dealing with changed English text
tags 474879 + pending
thanks
On 16/08/08 at 07:35 -0300, Christian Perrier wrote:
> tags 474879 patch
> thanks
>
> The attached patch adds more information about two topics:
>
> - how to "unfuzzy" strings when doing a change in English texts for
> debconf templates which has no impact on translations
>
> - how to call for translation updates when doing a change in English
> text that *has* an impact on translations
>
> --
>
>
>
> --- best-pkging-practices.dbk.old 2008-08-12 22:26:55.987121165 -0300
> +++ best-pkging-practices.dbk 2008-08-16 07:30:46.100519160 -0300
> @@ -755,30 +755,49 @@
> </para>
> <para>
> Avoid changing templates too often. Changing templates text induces more work
> -to translators which will get their translation fuzzied. If you plan changes
> -to your original templates, please contact translators. Most active
> +to translators which will get their translation fuzzied. A fuzzy translation is
> +a string for which the original changed since it was translated, therefore
> +requiring some update by a translator to be usable. When changes are small
> +enough, the original translation is kept in PO files but marked as
> +<literal>fuzzy</literal>.
> +</para>
> +<para>
> +If you plan to do changes
> +to your original templates, please use the notification system provided with
> +the <systemitem
> +role="package">po-debconf</systemitem> package, namely the <command>
> +podebconf-report-po</command>, to contact translators. Most active
> translators are very responsive and getting their work included along with your
> modified templates will save you additional uploads. If you use gettext-based
> -templates, the translator's name and e-mail addresses are mentioned in the po
> -files headers.
> +templates, the translator's name and e-mail addresses are mentioned in the PO
> +files headers and will be used by <command>
> +podebconf-report-po</command>.
> +</para>
> +<para>
> +A recommended use of that utility is:
> </para>
> +<programlisting>cd debian/po && podebconf-report-po --languageteam --withtranslators --call --deadline="+10 days"</programlisting>
> <para>
> -The use of the <command>podebconf-report-po</command> from the <systemitem
> -role="package">po-debconf</systemitem> package is highly recommended to warn
> -translators which have incomplete translations and request them for updates.
> +This command will first synchronize the PO and POT files in debian/po with
> +the templates files listed in <filename>debian/po/POTFILES.in</filename>.
> +Then, it will send a call for translation updates to the language team
> +(mentioned in the <literal>Language-Team</literal> field of each PO file)
> +as well as the last translator (mentioned in
> +<literal>Last-translator</literal>). Finally, it will also send a call for
> +new translations, in the &email-debian-i18n; mailing list.
> +</para>
> +<para>
> +Giving a deadline to translators is always appreciated, so that they can
> +organize their work. Please remember that some translation teams have a
> +formalized translate/review process and a delay lower than 10 days is
> +considered as reasonable. A shorter delay puts too much pressure on translation
> +teams and should be kept for very minor changes.
> </para>
> <para>
> If in doubt, you may also contact the translation team for a given language
> (debian-l10n-xxxxx@&lists-host;), or the
> &email-debian-i18n; mailing list.
> </para>
> -<para>
> -Calls for translations posted to &email-debian-i18n; with the
> -<filename>debian/po/templates.pot</filename> 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.
> -</para>
> </section>
>
> <section id="s6.5.2.3">
> @@ -787,15 +806,89 @@
> When the text of a debconf template is corrected and you are <emphasis
> role="strong">sure</emphasis> that the change does <emphasis
> role="strong">not</emphasis> affect translations, please be kind to translators
> -and unfuzzy their translations.
> +and <emphasis>unfuzzy</emphasis> their translations.
> </para>
> <para>
> If you don't do so, the whole template will not be translated as long as a
> translator will send you an update.
> </para>
> <para>
> -To <literal>unfuzzy</literal> translations, you can proceed the
> -following way:
> +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.
> +</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:
> +</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>
> +</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>.
> +</para>
> +</listitem>
> +<listitem>
> +<para>
> +Check that this change only applied to the place where you really intend
> +to make it and <emphasis role="strong">not</emphasis> in another place
> +where the original string is appropriate. That specifically applies to
> +change in punctuation, for instance.
> +</para>
> +</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.
> +</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.
> +</para>
> +</listitem>
> +<listitem>
> +<para>
> +Run <command>debconf-updatepo</command>
> +</para>
> +</listitem>
> +<listitem>
> +<para>
> +Check the <filename>foo.po</filename> reference file. Its statistics should
> +not be changed:
> +</para>
> +<programlisting>
> +msgfmt -o /dev/null --statistics debian/po/foo.po
> +</programlisting>
> +</listitem>
> +<listitem>
> +If the file's statistics changed, you did something wrong. Try again
> +or ask for help on the &email-debian-i18n; mailing list.
> +</listitem>
> +</orderedlist>
> +<para>
> +Gettext utilities method:
> </para>
> <orderedlist numeration="arabic">
> <listitem>
> @@ -850,7 +943,7 @@
> <title>Do not make assumptions about interfaces</title>
> <para>
> Templates text should not make reference to widgets belonging to some debconf
> -interfaces. Sentences like If you answer Yes... have no meaning for users of
> +interfaces. Sentences like <emphasis>If you answer Yes...</emphasis> have no meaning for users of
> graphical interfaces which use checkboxes for boolean questions.
> </para>
> <para>
> @@ -868,12 +961,12 @@
> <section id="s6.5.2.5">
> <title>Do not use first person</title>
> <para>
> -You should avoid the use of first person (I will do this... or We
> -recommend...). The computer is not a person and the Debconf templates do not
> +You should avoid the use of first person (<emphasis>I will do this...</emphasis> or <emphasis>We
> +recommend...</emphasis>). The computer is not a person and the Debconf templates do not
> speak for the Debian developers. You should use neutral construction. Those
> of you who already wrote scientific publications, just write your templates
> -like you would write a scientific paper. However, try using action voice if
> -still possible, like Enable this if ... instead of This can be enabled if ....
> +like you would write a scientific paper. However, try using active voice if
> +still possible, like <emphasis>Enable this if ...</emphasis> instead of <emphasis>This can be enabled if...</emphasis>.
> </para>
> </section>
>
> @@ -925,7 +1018,36 @@
> <para>
> A choice between one of a number of values. The choices must be specified in a
> field named 'Choices'. Separate the possible values with commas and spaces,
> -like this: Choices: yes, no, maybe
> +like this: <literal>Choices: yes, no, maybe</literal>.
> +</para>
> +<para>
> +If choices are translatable strings, the 'Choices' field may be marked as
> +translatable by using <literal>__Choices</literal>. The double underscore will split out
> +each choice in a separate string.
> +</para>
> +<para>
> +The <command>po-debconf</command> system also offers interesting possibilities
> +to only mark <emphasis role="strong">some</emphasis> choices as translatable.
> +Example:
> +</para>
> +<programlisting>
> +Template: foo/bar
> +Type: Select
> +#flag:translate:3
> +__Choices: PAL, SECAM, Other
> +_Description: TV standard:
> + Please choose the TV standard used in your country.
> +</programlisting>
> +<para>
> +In that example, only the 'Other' string is translatable while others
> +are acronyms that should not be translated. The above allows only
> +'Other' to be included in PO and POT files.
> +</para>
> +<para>
> +The debconf templates flag system offers many such possibilities. The
> +<citerefentry>
> +<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
> +</citerefentry> manual page lists all these possibilities.
> </para>
> </section>
>
> @@ -1168,7 +1290,7 @@
> <para>
> This special field allow translators to put the most appropriate choice
> according to their own language. It will become the default choice when their
> -language is used while your own mentioned Default Choice will be used chan
> +language is used while your own mentioned Default Choice will be used when
> using English.
> </para>
> <para>
> @@ -1522,7 +1644,7 @@
> distributing at any point in time. All that can be expected is that it is
> identical to something that upstream once <emphasis>did</emphasis> distribute.
> If a difference arises later (say, if upstream notices that he wasn't using
> -maximal compression in his original distribution and then
> +maximal comression in his original distribution and then
> re-<command>gzip</command>s it), that's just too bad. Since there is no good
> way to upload a new <literal>.orig.tar.gz</literal> for the same version, there is not even any
> point in treating this situation as a bug. </para> </footnote> This makes it
Thanks, applied (with changes suggested by Esko Arajärvi).
--
| Lucas Nussbaum
| lucas@lucas-nussbaum.net http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr GPG: 1024D/023B3F4F |
Reply to: