From: lucas Date: Thu, 22 Jan 2009 23:40:41 +0000 (+0000) Subject: Updated documentation on translation updates. (#474879) X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=57b86270cb54684a74f4e19f4333e1fe427a2b12;hp=d0b4400fd11a4af4a17beefd4d6babac7413488e;p=developers-reference.git Updated documentation on translation updates. (#474879) git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@5797 313b444b-1b9f-4f58-a734-7bb04f332e8d --- 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. diff --git a/debian/changelog b/debian/changelog index b8f439e..c3b6cc3 100644 --- a/debian/changelog +++ b/debian/changelog @@ -33,8 +33,11 @@ developers-reference (3.4.1) UNRELEASED; urgency=low Closes: #500371. * Document usertags. Thanks to Chris Lamb for the patch. Closes: #367876. + * Updated documentation on translation updates. + Thanks to Christian Perrier for the patch. + Closes: #474879. - -- Lucas Nussbaum Fri, 23 Jan 2009 00:25:45 +0100 + -- Lucas Nussbaum Fri, 23 Jan 2009 00:36:50 +0100 developers-reference (3.4.0) unstable; urgency=low