[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

[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-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org



Reply to: