internationalized documentation with mallard ?

On Wed, 2011-08-24 at 12:38 +0200, Jochen georges wrote:
> Hello,
> 
> I am looking for an easy to use tool to make a helpsystem for a
> java-application.
> 
> It should provide the possibility of an internationalized documentation.
> 
> Is that possible with mallard?
> 
> Thanks for your answers!

There are a lot of things you'll have to take care of for a
fully internationalized help system. For example, you'll need
to be able to load the document in the correct language based
on the user's locale. This is kind of outside the scope of
Mallard, which is just the document markup. I can give some
tips on how to do that with Mallard documents though.

The bulk of the work is going to be in translating your files
into other languages. For that, you *really* want to be using
some sort of message-based translation system, like PO files
or XLIFF. Don't make your translators do entire pages without
any sort of change tracking.

For translating Mallard using PO files, take a look at itstool:

 http://itstool.org/

It extracts paragraphs and other block elements and puts them
into PO files for your translators. It then merges translations
from PO files with the original pages to create translated pages.
Everything it knows about how to deal with an XML vocabulary
comes from ITS rules. ITS (Internationalization Tag Set) is a
W3C recommendation for marking localization-related information
in XML.

The nice thing about ITS is that you can override the built-in
rules for special cases. For example, you could mark a run of
text as untranslatable, and itstool won't put it into the PO
file.

XML formats in general make localization easier, because they're
easily parsed and there's a wealth of tools for XML. But there
are things a format can do better or worse about, and you should
be aware of those things.

  http://projectmallard.org/1.0/details.html

Take a look at the three topics under "Internationalization and
Localization" for more details about internationalizing Mallard
documents. And if you have any questions or concerns, feel free
to email the list.

-- 
Shaun McCance
Community Help Expert
http://syllogist.net/