[RFC] i18n and documentation
[Reply-To: d-i18n, Cc: d-doc from which this discussion comes from]
Hello,
the intro-i18n document explains what i18n does mean for programs,
but it does not cover documentation. Having guidelines for
documentation writers to help translators would be of great help,
so let's gather some ideas.
I will present here a translator's (and revierwer's) view. If we
agree on what he needs to perform his job, we can deduce what features
l10n tools should provide, and how docs should be written to help
translators.
Examples at bottom illustrate these points.
A. Requested features
======================
1) Anyone should be able to review translations
--------------------------------------------
The translator knows which version he worked on, and is able
to check for new revisions and incorporate changes.
But sometimes he is MIA, and if his translation does not
give version information, it may be hard to guess them.
So translated documents should be bound to a unique revision
of original document (either via a CVS revision number, or any
other ID).
2) Reviewers must know to whom send fixes
--------------------------------------
Documents are not always retrieved from a specific location,
they may be mirrored, shipped on CDs, etc. Thus translated
documents should contain informations on how to contact
translator.
3) Support for any encoding
------------------------
Self-explanatory.
4) Automatic reports are great
---------------------------
Ideally translator gets a notification message when his
translation gets outdated. He could also want to look at
some stats page, where he could know which doc needs care.
5) Give translation status to original author
------------------------------------------
Original author may want to know if documents are up to date
or not (e.g. to contact translator, or remove too outdated
translations).
6) Freedom for translations
------------------------
It is sometimes desirable to add or remove stuff in order to
improve accuracy for language-specific parts.
7) Large documents are difficult to manage
---------------------------------------
It would help if large documents could be divided into smaller
pieces.
Others?
B. Examples
============
a) PO files
An header gives informations on encoding (2) and translator (3).
Strictly speaking, (1) is not satisfied, because there is no
mention of a unique ID bound to original version. But there is
room for such an ID. The Free Translation Project has a
mail-driven robot
http://www.iro.umontreal.ca/contrib/po/HTML/status.html
to perform (4). Gettext provide tools for (5), but does not
allow (6). (7) is the natural way to deal with PO files.
b) Debian web site
Translated pages are bound to CVS revision number of original
(1). Due to the nature of documents, (2) is performed via a link
to a contact page. Support for encodings (3) is not ideal,
because some files contain translated strings for all languages.
A cron job can contact maintainers of outdated translations (4),
and translation status is available online (5). Translator is
free to change text (6), but large pages are hard to manage (7),
e.g. CVS is not always helpful when paragraphs are reordered.
We could gather other examples to illustrate strengths and weaknesses of
every approach.
Denis
--
To UNSUBSCRIBE, email to debian-i18n-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: