Please remember during the following to always work with DocBook files only -- no LinuxDoc, no HTML. While you may use HTML sometimes for reading and testing if everything works, always make your changes to the DocBook files exclusively. So whatever you do, first take a look at the first lines of the files you are working with and make sure they show something like: <!DOCTYPE Book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN">.
Then find out if a translation of the respective doc already exists, either by checking out WebCVS or Tobias Burnus' documentation statistics for your language.
If a translation does exist, try to get a list of the changes that were made to the original since your existing translation. You can get such a list either by using the "diff" feature of WebCVS as described in the (see the last section) or a similar tool on your local system like Kdiff. The real problem is often to find out exactly to which version of the original the diff should refer. The version numbers of the originals and the corresponding data in the translation should help you with this -- most of the time.
If a translation does not exist, get the English original (usually from packagedir/doc/), save it to a new location and set the attribute "lang" in the <book> tag to the official abbreviation for your language, e.g. <book lang="sk"> if you translate to Slovak. This will provide translated navigation bars if your document is processed to HTML.
With regard to version number and date, it might be a good idea to enter the date of your translation here for future reference -- either instead of the data that's given in the original or in addition to it. The contents of <revhistory> should be handled in a similar fashion. (Always be aware how difficult it can be some day to make a reliable diff if you don't define exactly which translation refers to what version of the original.) If there is so-called "meta-information" (mostly in <bookinfo>), you should translate it like anything else.
Now start the main translation. It may be a good idea to not translate word by word or even sentence by sentence but to always read the whole paragraph before writing down a translation. If you get stuck and don't know how to translate something it's often a good idea to insert a comment like " <!--FIXME-->" which allows to easily find that problem spot again. Most important in any case: Don't touch the SGML tags or any structural elements, except maybe the "IDs" (see next section). Especially, don't touch anything that's tagged with <anchor>. Otherwise the program may not be able to access the respective section.
Accordingly, a German translation of the first paragraphs of David Rugge's template.docbook could look as follows. It doesn't matter if you understand German. Just take a look at what's tranlated or not.
First the original:
<!DOCTYPE Book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN"> <book lang="EN" ID="Kapp"> <bookinfo> <title>The Kapp Handbook</title> <date>03/04/1999</date> <releaseinfo>1.1.0</releaseinfo> <abstract> <para> <application>Kapp</application> is an application specially designed to do nothing you would ever want. </para> </abstract> </bookinfo> <chapter ID="Introduction"> <title>Introduction</title> <para> <application>Kapp</application> is a program that lets you do absolutely nothing. Please report any problems or feature requests to the KDE mailing lists.</para> <para ID="mylink"> This is a paragraph that will be linked to with a link tag.<Anchor ID="anotherlink"> Konqui was here.</para> <para> The above paragraph can be located <Link LinkEnd="mylink">here</Link>. </para> </chapter> |
Now the translation:
<!DOCTYPE Book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN"> <book lang="de" ID="Kapp"> <bookinfo> <title>Das Kapp Handbuch</title> <date>10/27/1999</date> <releaseinfo>1.1.0</releaseinfo> <abstract> <para> <application>Kapp</application> ist ein Programm, das speziell dazu entworfen wurde, genau das zu tun, was Sie nie brauchen werden. </para> </abstract> </bookinfo> <chapter ID="Introduction"> <title>Einleitung</title> <para> <application>Kapp</application> ist ein Programm, das einfach nutzlos ist. Bitte berichten Sie jedes Problem oder sonstige Anfragen an die KDE Mailinglisten. </para> <para ID="mylink"> Das ist ein Abschnitt, auf den mit einem Link-Tag verwiesen wird. <Anchor ID="anotherlink">Konqui war hier. </para> <para> Den obigen Abschnitt finden Sie <Link LinkEnd="mylink">hier</Link>. </para> </chapter> |
The place for your own part in this you will usually find at the end of the document in a section named <title>Credits and License</title> or the like. This should read (according to the template.dookbook by David Rugge in ksgmltools) about as follows:
<chapter ID="Credits"> <title>Credits and License</title> <para> <application>Kapp</application> </para> <para> Program copyright 1997 John Q. Hacker <email>jqh@kde.org</email> </para> <para> Contributors: <itemizedlist> <listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para> </listitem> <listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para> </listitem> </itemizedlist> </para> <para> Documentation copyright 1999 George N. Ugnacious <email>gnu@kde.org</email> </para> <para> Translations done by: <itemizedlist> <listitem> <para>Babel D. Fish <email>babelfish@kde.org</email> (Sanskrit)</para> </listitem> </itemizedlist> </para> <para> This program is licensed under the terms of the <ulink URL="common/gpl-license.html">GNU GPL</ulink>. </para> </chapter> |
The very last thing you should probably do are the screenshots. Especially make sure that the GUI translation isn't going to change anymore if you start with them. It may also be a good idea to talk to your co-translators as to what screen layout or theme you are using to keep the look consistent (if you think anything else should be used than just the default layout). Also remember that the screenshots have to be in PNG format, not GIF. See also the following section.