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 | [email protected] http://www.lucas-nussbaum.net/ | | jabber: [email protected] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
