[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Re: Translated IDs ?
From:       Eric Bischoff <ebisch () cybercable ! tm ! fr>
Date:       1999-11-21 10:57:04
[Download RAW message or body]

I have been asked to summarize why we should translate the chapter and section
names in the documentation (to German, Italian, French etc...). As there are
consequences for the application developpers, this message is being posted to
kde-devel@kde.org as well.

-------------------------------------------------------
Abstract :

It is currently discussed whether the documentation translators should use
translated IDs for chapters and sections or not. It seems very clear to me that
they should translate them. Therefore application developpers should make calls
like invokeHTMLHelp(i18n(introduction.html")); in their applications.
The invokeHTMLHelp() function could even be changed to call transparently i18n()
function. The reasons for doing like that are user-friendliness and avoiding a
huge correction work to the translators.

-------------------------------------------------------
Explanations :

1 - We need names for the HTML files because a single docbook file is
transformed into several chunks, one for each chapter and top-level section.

2 - "Cryptic" names like x040.html, chosen by the DocBook tools as a default,
are not a solution, because we have no control on the numbering scheme (almost
random). It isn't like the old LinuxDoc tools that used index-1.html,
index-2.html, etc. We need to have control over this numbering because :
2a - if we decide to store again the HTML files in the CVS repository, they
shouldn't change their name each time they are regenerated, because CVS stores
only the differences between one version and another to save room.
2b - if a documentation is called from an application through invokeHTMLHelp()
function, the application should know the name of the file holding the
documentation !

3 - The docbook tools allow to have control upon the file names by using the ID
attribute of the chapters and the sections. As a side effect, it allows to have
"human-understable" names like introduction.html, shortcuts.html, credits.html,
etc. It is not true to say that the user doesn't see these names : he/she may
want to browse the contents of his/her hard disk to go directly to the parts
he/she's interested in. If we follow the idea of having fully "user-friendly"
names, they should be translated for the convienence of the user.

4 - Since we didn't want names to be cryptic but stored as IDs, we
(with Frederik's great help) made them mandatory so that we ensured that no one
will forget to give them. This implied that the automated conversion would
choose unique IDs when changing linuxdoc sections into docbook chapters and
sections. The most logical way to do that was to use the contents of the next
<title> tag. This leads sometimes to "funny names" like
"kpagereinstellenundweiteremoumlglichkeiten.html". To make some of these names
less funny, we will need to shorten them during manual cleanup. But very often
they are just correct and no change is needed.

5 - Some other IDs already existed in LinuxDoc (they are not many) and have
just been copied without any change during automated conversion. But half of the
time they were already translated to French, German, etc, in the original
LinuxDoc, so those IDs are "native language" in DocBook too.

6 - Thus almost all the IDs are ALREADY translated. This is why, according to
me, it will be a HUGE AND ALMOST USELESS WORK to change them to English again.

7 - Now comes the problem of the NEW translations. We could leave the IDs in
English, but this would introduce inconsistency across the docs. And it doesn't
solve any problem with respect to old docs.

8 - The only problem with translated documentation names is that you would need
to use i18n() function when using "invokeHTML()" function. Therefore the
translator should be aware that he/she must choose the same name in the .po and
in the .docbook. There are 3 ways to solve the problem: 8a - Don't use
translated names only for those files - again, this introduces inconsistency
across the docs. 8b - Use invokeHTMLHelp(i18n("introduction")) in the
application and pass a comment to the .po file so that the translator is aware
that he/she should choose the same name that is in the .docbook file.
8c - Change the InvokeHTMLHelpFile so that the .html file extension is not
automatically added, so the problem is very clear to the translator. Then call 
invokeHTMLHelp(i18n("introduction.html")).
According to me, solution 8c) is the best. The invokeHTMLHelp() function could
even transparently call i18n() function before opening the documentation.
Please take into consideration that:
8d - calls to invokeHTMLHelp are not many
8e - usually they call main the main index file called "index.html" in every
language (because it is not obtained through an ID attribute).

-------------------------------------------------------

Eric
--
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                    Konqui         \__=v
 __________________________________________________
 Eric Bischoff   -   mailto:ebisch@cybercable.tm.fr

[prev in list] [next in list] [prev in thread] [next in thread]