[Uml-devel] Introduction to doc translation

[Sebastian Stein]

Hohoho,

I'm now the master of the doc translation system ;-) I want to give a short
introduction. As you may have seen, I started committing some of the
translation, unfortunally I have only translated 2 small files, but hey, it
is a beginning.

The process is to take the docbook files, convert them to pot files, compare
the pot file with the po files of the translation, merge both, update the po
files with kbabel and convert the po files back to docbook. These docbook
files will be shipped as translated handbook.

At the beginning it is needed to create the po files. It is done by:

cd doc/en/
xml2pot original.docbook > original.docbook.pot
cp original.docbook.pot ../de/original.docbook.po

I have allready done this, so this is only interesting for adding a new
translation.

Now, everytime the original docbooks in the en/ dir are updated, the changes
have to be merged into these po files. Here we go:

cd doc/en/
xml2pot original.docbook > original.pot
msgmerge -o ../de/original.docbook.po ../de/original.docbook.po \
original.docbook.pot

Now it is KBabel time. Open the po file and KBabel will show all
untranslated, updated, fuzzy... strings and you have to translate them and
save it back to the po file.

The last step is to generate the translated docbook file from the po file.
It can be done like this:

cd doc/en/
po2xml original.docbook ../de/original.docbook.po > ../de/original.docbook

There seems to be a bug in po2xml. It inserts linebreaks in the docbook file
where there shouldn't be, e.g.:

</par
a>

These linebreaks make the meinproc compiler fail. So I remove all linebreaks
from the docbook file with sed:

cd doc/en/
po2xml original.docbook ../de/original.docbook.po | sed -e \
":start;N;s/\n//;b start" > ../de/original.docbook

I don't know if this works on any system without GNU sed, the N command
might be a problem.

Ok, to sum everything up, I can tell you, that I have prepared 2 small
scripts. They are attached to this mail. You should put them in the uml root
dir. The scripts have hardcoded the language de, but it would be easy to
change if sometimes a new language shows up.

So to translate the German doc files, you have to do the following steps:

1. Update your CVS copy (at least the doc/ directory)
2. Run splitdoc.sh to merge all updates from the original docbook files into
the translated files (po)
3. Translate the remaining items in the po files using KBabel
4. Run the makedoc.sh script to generate the translated docbook files
5. Commit your changes to CVS.

You may have noticed that I added the po files to CVS as well. These files
shouldn't be distributed to the end user. But it is better to have these
files in CVS than to split the translated docbook files into po files each
time the handbook gets updated. It is the way recommened by the KDE
developers.

Ok, at the end I like to tell you as well, that I will convert this message
into a webpage and upload it to uml.sf.net as well as the 2 scripts. But
this may take some days.

If you are interested more in handbook translation, you can read the
translation howto on i18n.kde.org. If you can read German, you can also look
for the thread "docboox -> xml Konvertierung" started at 2002/11/30 on
kde-i18n-de at kde.org (http://lists.kde.org/) by myself.

Steinchen
-- 
Umbrello UML Modeller
Description     : UML diagram drawing tool for KDE with code generation
Homepage        : http://www.umbrello.org/
Bug report      : http://sourceforge.net/tracker/?group_id=24919&atid=382951
Feature request : http://sourceforge.net/tracker/?group_id=24919&atid=382954
-------------- next part --------------
A non-text attachment was scrubbed...
Name: makedoc.sh
Type: application/x-sh
Size: 169 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/umbrello-devel/attachments/20021204/bbb74694/attachment.sh>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: splitdoc.sh
Type: application/x-sh
Size: 198 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/umbrello-devel/attachments/20021204/bbb74694/attachment-0001.sh>