Re: Developers' reference - improvable section on l10n
Hi,
here comes the first attempt with some comments (marked >>>).
Cheers
Martin
**************************************************************************************
Chapter 8. Internationalization and Translations
*Table of Contents*
8.1. How translations are handled within Debian <l10n.html#l10n-handling>
8.2. I18N & L10N FAQ for maintainers <l10n.html#l10n-faqm>
8.2.1. How to get a given text translated <l10n.html#l10n-faqm-tr>
8.2.2. How to get a given translation reviewed <l10n.html#l10n-faqm-rev>
8.2.3. How to get a given translation updated
<l10n.html#l10n-faqm-update>
8.2.4. How to handle a bug report concerning a translation
<l10n.html#l10n-faqm-bug>
8.3. I18N & L10N FAQ for translators <l10n.html#l10n-faqtr>
8.3.1. How to help the translation effort <l10n.html#l10n-faqtr-help>
8.3.2. How to provide a translation for inclusion in a package
<l10n.html#l10n-faqtr-inc>
>>> I suggest rephrasing the questions (s/to/do I/) and perhaps a question
>>> mark at the end.
8.4. Best current practice concerning l10n <l10n.html#l10n-best>
Debian supports an ever-increasing number of natural languages. Even if
you are a native English speaker and do not speak any other language, it
is part of your duty as a maintainer to be aware of internationalization
issues. (A widely used abbreviation for internationalization is i18n
because there are 18 letters between the 'i' and the 'n' in
internationalization). Therefore, even ifyou are ok with English-only
programs, you should read most of this chapter.
According to Introduction to i18n
<http://www.debian.org/doc/manuals/intro-i18n/> from Tomohiro KUBOTA,
I18N (internationalization) means modification of a software or related
technologies so that a software can potentially handle multiple
languages, customs, and so on in the world. L10N (localization)
means implementation of a specific language for an already
internationalized software.
>> My feeling is that "customs, and so on in the world." is somehow
>> infortunate. It sounds like "German English".
l10n and i18n are interconnected, but their problems are very different.
It's quite easy to allow a program to change the language in which texts are
displayed based on user settings, but it is very time consuming to actually
translate these messages. Setting the character encoding is trivial, but
adapting the code to manage several character encodings is a really hard
problem.
>>> I didn't change "a really hard problem." But again, it sounds German.
Setting aside the i18n problems, where no general guideline can be
given, there is actually no central infrastructure for l10n within
Debian which could be compared to the buildd mechanism for porting. So
most of the work has to be done manually.
8.1. How translations are handled within Debian
Handling translation of the texts contained in a package is still a
manual task. 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
projects like the Free Translation Project
<http://translationproject.org/>, the Gnome translation Project
<http://live.gnome.org/TranslationProject> or the KDE one
<http://i18n.kde.org/>. At <http://www.debian.org/intl/l10n/> you
can find the central Debian statistics about translation files found in
the actual packages that are being maintainded using the gettext
infrastructure. There are overview pages for debconf, program messages
and manual page translations (http://www.debian.org/intl/l10n/po-debconf/,
http://www.debian.org/intl/l10n/po/ and
http://www.debian.org/intl/l10n/po4a/)
linking to the individual language pages. At
http://i18n.debian.net/debian-l10n/ there are coordination pages for some
translation teams.
>>> I still would like to know how the po files for programm messages
>>> and manual pages actually get there. But perhaps this information
>>> exceeds the scope of this text.
An effort to translate the package descriptions (the Debian Description
Translation Project, DDTP) started long ago. Translators have the choice
between an email and a web interface (DDTSS,
http://ddtp.debian.net/ddtss/index.cgi/). The package descriptions are
automatically extracted from debian/control and stored in the DDTP
database.
They are not integrated into the translation infrastructure as well as the
other translations. Before lenny APT could use the translated package
descriptions only when specifically configured.
>>> Long ago means when?
>>> "even if very little support is offered by the tools to actually use
>>> them". What is the current situation for tools other than APT?
For web pages, each l10n team has access to the relevant VCS, and the
statistics are available from the central Debian translation statistics
site.
For general documentation about Debian, the process is more or less the
same as for the web pages (the translators have access to the VCS), but
there are no statistics pages.
Most notably, the KDE project handles translation of its documentation
in the same way as its program messages.
There is an effort to handle Debian-specific man pages within a specific
VCS repository <http://cvs.debian.org/manpages/?cvsroot=debian-doc>.
>>> Many entrys eight are from years ago, little use in German, more in
French.
>>> Recent german translations found on
>>> http://www.debian.org/international/l10n/po4a/de aren't stored there
>>> but in their respective packages. This paragraph should be skipped.
>>> Perhaps this resource is of no use any longer?
8.2. I18N & L10N FAQ for maintainers
This is a list of problems that maintainers may face concerning i18n and
l10n. While reading this, keep in mind that there is no real consensus
on these points within Debian, and that this is only advice. If you have
a better idea for a given problem, or if you disagree on some points,
feel free to provide your feedback, so that this document can be enhanced.
8.2.1. How to get a given text translated
For |debconf| templates, maintainers should use the |po-debconf| package
to ease the work of translators. Especially when preparing the initial
packaging, please consider a review on debian-l10n
(http://wiki.debian.org/I18n/SmithReviewProject).
To translate package descriptions, "you have nothing to do"; the DDTP
infrastructure will dispatch the material to translate to volunteers
with no need for interaction from your part. As with the debconf templates
you should consider asking debian-l10n for some polish. Good english eases
the translation work a lot. You should also consider providing an initial
description in your mother tongue because you as maintainer know your
package best.
For the program messages and manual pages make sure that your material is
stored at the sites mentioned above. For some formats (manpages, POD, XML
(generic, DocBook, XHTML, Dia, Guide, or WML), SGML, TeX (generic, LaTeX,
or Texinfo), text (simple text files with some formatting, markdown, or
AsciiDoc), INI, KernelHelp) po4a helps you providing a po file. Perhaps a
call for translations on debian-i18n and/or the debian-l10n-lists will
activate a volunteer. Once the work is done, you will get your translated
document from them in your mailbox.
8.2.2. How to get a given translation reviewed
From time to time, individuals translate some texts in your package and
will ask you for inclusion of the translation in the package. This can
become problematic if you are not fluent in the given language. It is a
good idea to send the document to the corresponding l10n mailing list,
asking for a review. Once it has been done, you should feel more
confident in the quality of the translation, and feel safe to include it
in your package.
8.2.3. How to get a given translation updated
If you have some translations of a given text lying around, each time
you update the original, you should ask the previous translator to
update the translation with your new changes. Keep in mind that this
task takes time; at least one week to get the update reviewed and all.
If the translator is unresponsive, you may ask for help on the
corresponding l10n mailing list. If everything fails, don't forget to
put a warning in the translated document, stating that the translation
is somehow outdated, and that the reader should refer to the original
document if possible.
Avoid removing a translation completely because it is outdated. Old
documentation is often better than no documentation at all for
non-English speakers.
8.2.4. How to handle a bug report concerning a translation
The best solution may be to mark the bug as forwarded to upstream, and
forward it to both the previous translator and his/her team (using the
corresponding debian-l10n-XXX mailing list).
8.3. I18N & L10N FAQ for translators
While reading this, please keep in mind that there is no general
procedure within Debian concerning these points, and that in any case,
you should collaborate with your team and the package maintainer.
8.3.1. How to help the translation effort
Choose what you want to translate, make sure that nobody is already
working on it (using your debian-l10n-XXX mailing list), translate it,
get it reviewed by other native speakers on your l10n mailing list, and
provide it to the maintainer of the package (see next point).
8.3.2. How to provide a translation for inclusion in a package
Make sure your translation is correct (asking for review on your l10n
mailing list) before providing it for inclusion. It will save time for
everyone, and avoid the chaos resulting in having several versions of
the same document in bug reports.
The best solution is to file a regular bug containing the translation
against the package. Make sure to use the 'PATCH' tag, and to not use a
severity higher than 'wishlist', since the lack of translation never
prevented a program from running.
8.4. Best current practice concerning l10n
* As a maintainer, never edit the translations in any way (even to
reformat the layout) without asking on the corresponding l10n
mailing list. You risk for example breaking the encoding of the
file by doing so. Moreover, what you consider an error can be
right (or even needed) in the given language.
* As a translator, if you find an error in the original text, make
sure to report it. Translators are often the most attentive
readers of a given text, and if they don't report the errors they
find, nobody will.
* In any case, remember that the major issue with l10n is that it
requires several people to cooperate, and that it is very easy to
start a flamewar about small problems because of
misunderstandings. So if you have problems with your interlocutor,
ask for help on the corresponding l10n mailing list, on
debian-i18n, or even on debian-devel (but beware, l10n discussions
very often become flamewars on that list :)
* In any case, cooperation can only be achieved with *mutual respect*.
Reply to: