Bug#1042779: developers-reference: overhaul of chapter about i18n / l10n

[Holger Levsen]

Hi Holger,

On Mon, Jul 31, 2023 at 10:49:20PM +0200, Holger Wansing wrote:
> yesterday I was a bit shocked when reading chapter 8 of the developers-ref:
> https://www.debian.org/doc/manuals/developers-reference/l10n.en.html
> 
> That chapter has several wrong/bad sentences (or is heavily outdated, if that
> things have been correct like that at some time).
> 
> I comment here on the different parts; a complete patch which integrates all
> this proposals is attached to this mail.

thank you very much for this! I'll upload shortly. In future please also feel 
free
to directly commit fixes to git if you are confident about the changes.


-- 
cheers,
Holger

 ⢀⣴⠾⠻⢶⣦⠀
 ⣾⠁⢠⠒⠀⣿⡁  holger@(debian|reproducible-builds|layer-acht).org
 ⢿⡄⠘⠷⠚⠋⠀  OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
 ⠈⠳⣄

This is the year of gpg on the desktop! (Gunnar Wolf)


signature.asc
Description: PGP signature

Bug#1042779: developers-reference: overhaul of chapter about i18n / l10n

[Holger Wansing]

Package: developers-reference
Severity: normal


Hi,

yesterday I was a bit shocked when reading chapter 8 of the developers-ref:
https://www.debian.org/doc/manuals/developers-reference/l10n.en.html

That chapter has several wrong/bad sentences (or is heavily outdated, if that
things have been correct like that at some time).

I comment here on the different parts; a complete patch which integrates all
this proposals is attached to this mail.



"For program messages, the gettext infrastructure is used most of the time. 
Most of the time, the translation is handled upstream within projects like the 
Free Translation Project, the GNOME Translation Project or the KDE Localization 
project.


... is used most of the time. Most of the time, the translation ...

Please avoid this doubled use of "most of the time" in direct repeating.
(only cosmetic, yes.)



The only centralized resources within Debian are the Central Debian 
translation statistics, where you can find some statistics about the 
translation 
files found in the actual packages, but no real infrastructure to ease the 
translation process."


... where you can find some statistics ... but no real infrastructure to ease 
the 
translation process.

This is not true. The statistics page provides the possibility to directly
download the po files by one click! This is for sure much easier than
loading the whole source package, uncompress it and pick the po file out from
there! So, it's much more than just a statistics page, and it makes translators
work much easier!
(What was meant here is probably, that Debian has no own pootle or Weblate
server, where the translation can be done directly online?)




For debconf templates, maintainers should use the po-debconf package to ease 
the work of translators, who could use the DDTP to do their work (but the 
French and Brazilian teams don't). Some statistics can be found both on the 
DDTP site (about what is actually translated), and on the Central Debian 
translation statistics site (about what is integrated in the packages).


Here we have some wrong facts. The DDTP infrastructure is only for translating
the package descriptions!
It does not handle debconf template translations!
And the DDTP site does not have statistics about debconf template translations.
(Don't know, if this was different in the past, but this is the status quo.)



For package-specific documentation (man pages, info documents, other formats),
almost everything remains to be done.


This is also not true!
We have many translated manpages now for example, so we cannot say 
"nothing has been done on this".




For all other material (gettext files, man pages, or other documentation), the 
best solution is to put your text somewhere on the Internet, and ask on 
debian-i18n for a translation in different languages. Some translation team 
members are subscribed to this list, and they will take care of the translation 
and of the reviewing process. Once they are done, you will get your translated 
document from them in your mailbox.


... the best solution is to put your text somewhere on the Internet ...

This seems rather weird for me. Debian is such a huge community with much
infrastructure, we should not recommend to "put the text somewhere on the 
Internet". That sounds poor.


... Once they are done, you will get your translated document from them in 
your mailbox. ...

There is a big consensus, that translations are sent via wishlist bugreports.



Please find a patch attached (can be seen as a proposal, of course).


So long
Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/source/l10n.rst b/source/l10n.rst
index c66173d..8935907 100644
--- a/source/l10n.rst
+++ b/source/l10n.rst
@@ -42,7 +42,7 @@ manual task, and the process depends on the kind of text you want to see
 translated.
 
 For program messages, the gettext infrastructure is used most of the
-time. Most of the time, the translation is handled upstream within
+time. Often the translation is handled upstream within
 projects like the `Free Translation
 Project `__, the
 `GNOME Translation
@@ -51,7 +51,7 @@ Localization `__ project. The only centralized
 resources within Debian are the `Central Debian translation
 statistics `__, where you can find
 some statistics about the translation files found in the actual
-packages, but no real infrastructure to ease the translation process.
+packages and download those files.
 
 Package descriptions have translations since many years and Maintainers
 don't need to do anything special to support translated package
@@ -59,12 +59,9 @@ descriptions; translators should use the `Debian Description Translation
 Project (DDTP) `__.
 
 For ``debconf`` templates, maintainers should use the ``po-debconf``
-package to ease the work of translators, who could