The K Desktop Environment

Chapter 4. Doc Translation

The bulk of information on this subject is provided by the KDE documentation team and its coordinator Eric Bischoff. At the moment they offer:

The following sections of this HOWTO will only provide a few practical hints for translators who are trying their first steps in this area. Most of the contents is thanks to the German MiniHowto on Doc Translation by Matthias Kiefer.

4.1. SGML Files: DocBook Versus HTML and LinuxDoc

Like the translations of GUI files ("POs") the translations of online documentations are stored in the "kde-i18n" package, more exactly in "kde-i18n/$LANG/docs/". But while the originals for GUI translations (the "POTs") are also stored in the translations directory ("kde-i18n/templates/") the originals of the docs are stored with the packages where the programs themselves are in. For instance, the original of the kpager documentation is in "kdebase/doc/kpager/index.docbook" while the German translation would be in "kde-i18n/de/docs/kdebase/kpager/index.docbook".

What you have seen in real life situations as KDE online help was probably formatted in HTML. But the originals to this documentation are most definetely not HTML. For KDE 1x, they were originally written and maintained in "LinuxDoc" format and are now, for KDE 2, converted to "DocBook". All of these are subsets of "SGML" (including HTML), but very different subsets.

In case you have only a somewhat hazy idea about the meaning of "DocBook" and "SGML" (apart from the fact that it's something with "Standard Generalized Markup Language"): SGML allows the systematic encoding of documents by means of a "Document Type Definition" (DTD). HTML or DocBook are both "DTDs". What the definitions in these DTDs say is basically what formatting or other encoding elements are allowed in a certain sort of document and how these elements have to be organized. You cannot use the elements of one definition system (like HTML) in a text that follows another definition system (like DocBook). In other words: you cannot just use HTML tags in a DocBook text. So, whatever you do, don't write or translate HTML for KDE, only DocBook. Else you will risk to lose your work.

Basically the same as for HTML goes for older documentation in KDE which may still be formatted according to the "LinuxDoc DTD" from the days of KDE 1x: please do not touch these, either. They will be converted to DocBook soon. And, again, your work would be lost.

In case you are wondering what this SGML and DocBook business is all about and why we don't simply format everything in HTML from the outset instead of writing DocBook first and converting to HTML afterwards it has to suffice to say that things get a lot more unified and consistent that way and we get a lot of additional possibilities (like indexing, table of contents generation etc.) which we wouldn't have as easily in HTML.

As a translator, you don't need to be an expert in SGML. Basically, you can write your translation between the existing DocBook tags which are somewhat similar to the tags in other markup languages you may already know like (La)TeX or HTML. But the more you know about DocBook the easier your work will get, of course. So the already mentioned information sites of the documentation team provide the recommended reading for anyone who is working in this area.

In case you are looking for further information, the following things may also be of interest: