Re: [docbook-apps] Re: [Q] multilingual website?

[Lauri Watts <lauri at kde dot org>]

On Sunday 21 March 2004 09.09, Dave Pawson wrote:
> At 00:03 21/03/2004, luis miguel morillas wrote:
> >If we want to apply this workflow to docbook website sites,
> >i think we must to follow the next process:
> >
> >1. create docbook-original.xml files and layout.xml file.
> >2. generate docbook.po (xml2po) files and translate them (trasnlators
> > task) 3. generate docbook-translated.xml files (po2xml).
> >4. generate html files with xslt processor, hacking layout.xml to
> >    make the new docbook-translated.xml files.
>
> What do you expect the docbook-original.xml files to look like?

KDE's original docbook files are perfectly ordinary (and valid) docbook XML 
files.  We do use a customization layer on the DTD, but it's mostly to deal 
with our very extensive use of entities - there's actually only one single 
change to the DocBook DTD itself, and that is a restriction, to require 
specific elements in <bookinfo> that are normally optional.  

> With no content?

No, all the content is in the docbook files as normal

>    I don't know what a .po file is?

.po is the file format for GNU gettext, which is a very common translation 
format and toolchain.  There are very many editors available that can handle 
this format, or it can be edited in a plain text format.  It's the method 
used by virtually all open source UNIX based software (and then some) to 
translate the visible GUIs of applications (for instance, the menus, on 
screen dialogs, and command lines)  We just leveraged the existing very large 
userbase already translating KDE itself, so they can work in a (for them) 
familiar format that is specifically designed for translation.

I can make plenty of examples available, if you'd like to see them.

Our xml2po and po2xml are simply tools that convert xml into po format, and po 
back into valid docbook xml.

> Why not translate the docbook-original into x.en.xml and x.fr.xml?

That's exactly what these tools are for. However, translating in place in a 
docbook file is an enormous task, and synching changes in content in a 
paragraph based format such as documentation, is a very intense task.  .po 
aware editors can quickly point out which specific passages have changed, if 
those changes are markup, content, or just whitespace, and if they need 
translation at all.    It is a much better format for this than a docbook 
file, because it separates out things into single 'messages', where a message 
might be a menu item, or a single command line option (for an application 
GUI) or a <para> or a <term> or some other small and manageable chunk of 
text, for a docbook document.

We have something like 1500 docs translated into as many as 40 languages using 
this system, and support for very many more, there are 72 languages that have 
at least started translations, although, some of them are already abandoned.  

> Is there something special about the .po files that makes
> them easy to work with for translation?

Indeed, they make translation a breeze compared to working directly in 
docbook.

> Which files are used as the input to step 4?

po2xml creates valid docbook XML files entirely in the target language, which 
are then processed as normal.

You can see all this in action here:
http://docs.kde.org/

For instance here, the user manual for the Konqueror Browser, in 
English: http://docs.kde.org/en/3.2/kdebase/konqueror/
German: http://docs.kde.org/de/HEAD/kdebase/konqueror/
French: http://docs.kde.org/fr/HEAD/kdebase/konqueror/
Spanish: http://docs.kde.org/es/HEAD/kdebase/konqueror/

However, we're not doing the content negotiation, and only the three most 
complete languages are currently available in addition to English - this will 
change very soon, it's a little time consuming to set up initially, but once 
a language is added, the entire process is automated - a new english version 
appears when an updated is checked into CVS, and a new translated version 
appears when a translator checks in their update.  

Regards,
-- 
Lauri Watts
KDE Documentation: http://i18n.kde.org/doc/
KDE on FreeBSD: http://freebsd.kde.org/

Attachment: pgp00000.pgp
Description: signature