X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=best-pkging-practices.dbk;fp=best-pkging-practices.dbk;h=1f14722f71830b1d1c7fde3e52beb503d1dc2b72;hb=57b86270cb54684a74f4e19f4333e1fe427a2b12;hp=a3852bbf30e71970276a6ba42ed62ceea381e993;hpb=d0b4400fd11a4af4a17beefd4d6babac7413488e;p=developers-reference.git
diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index a3852bb..1f14722 100644
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -755,30 +755,49 @@ documentation (man po-debconf is a good start).
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
+fuzzy.
+
+
+If you plan to do changes
+to your original templates, please use the notification system provided with
+the po-debconf package, namely the
+podebconf-report-po, 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
+podebconf-report-po.
-The use of the podebconf-report-po from the po-debconf package is highly recommended to warn
-translators which have incomplete translations and request them for updates.
+A recommended use of that utility is:
+
+cd debian/po && podebconf-report-po --languageteam --withtranslators --call --deadline="+10 days"
+
+This command will first synchronize the PO and POT files in debian/po with
+the templates files listed in debian/po/POTFILES.in.
+Then, it will send a call for translation updates to the language team
+(mentioned in the Language-Team field of each PO file)
+as well as the last translator (mentioned in
+Last-translator). Finally, it will also send a call for
+new translations, in the &email-debian-i18n; mailing list.
+
+
+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 unreasonable. A shorter delay puts too much pressure on translation
+teams and should be kept for very minor changes.
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.
-
-Calls for translations posted to &email-debian-i18n; with the
-debian/po/templates.pot 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.
-
@@ -787,15 +806,89 @@ work.
When the text of a debconf template is corrected and you are sure that the change does not affect translations, please be kind to translators
-and unfuzzy their translations.
+and unfuzzy their translations.
If you don't do so, the whole template will not be translated as long as a
translator will send you an update.
-To unfuzzy translations, you can proceed the
-following way:
+To unfuzzy translations, you can use two methods. The first
+method does preventive search and replace actions in the
+PO files. The latter uses gettext utilities to unfuzzy
+strings.
+
+
+Preventive unfuzzy method:
+
+
+
+
+Try finding a complete translation file before
+the change:
+
+for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done
+
+The file only showing translated 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.
+
+
+
+
+Identify the needed change. In this example, let's assume the change is about
+fixing a typo in the word typo which was inadvertently
+written as tpyo. Therefore, the change is
+s/tpyo/typo.
+
+
+
+
+Check that this change is only applied to the place where you really intend
+to make it and not in any other place
+where the original string is appropriate. This specifically applies to
+change in punctuation, for instance.
+
+
+
+
+Modify all PO files by using sed. 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.
+
+
+cd debian/po
+for i in *.po; do sed -i 's/tpyo/typo/g' $i; done
+
+
+
+
+Change the debconf template file to fix the typo.
+
+
+
+
+Run debconf-updatepo
+
+
+
+
+Check the foo.po reference file. Its statistics should
+not be changed:
+
+
+msgfmt -o /dev/null --statistics debian/po/foo.po
+
+
+
+If the file's statistics changed, you did something wrong. Try again
+or ask for help on the &email-debian-i18n; mailing list.
+
+
+
+Gettext utilities method:
@@ -850,7 +943,7 @@ run debconf-updatepo again
Do not make assumptions about interfaces
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 If you answer Yes... have no meaning for users of
graphical interfaces which use checkboxes for boolean questions.
@@ -868,12 +961,12 @@ facts.
Do not use first person
-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 (I will do this... or We
+recommend...). 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 Enable this if ... instead of This can be enabled if....
@@ -925,7 +1018,36 @@ yes/no...
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: Choices: yes, no, maybe.
+
+
+If choices are translatable strings, the 'Choices' field may be marked as
+translatable by using __Choices. The double underscore will split out
+each choice in a separate string.
+
+
+The po-debconf system also offers interesting possibilities
+to only mark some choices as translatable.
+Example:
+
+
+Template: foo/bar
+Type: Select
+#flag:translate:3
+__Choices: PAL, SECAM, Other
+_Description: TV standard:
+ Please choose the TV standard used in your country.
+
+
+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.
+
+
+The debconf templates flag system offers many such possibilities. The
+
+po-debconf 7
+ manual page lists all these possibilities.
@@ -1168,7 +1290,7 @@ the _DefaultChoice trick.
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.