[haiku-development] Fwd: [haiku-doc] Organizing translations of User Guide/Welcome Package
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: haiku-development@xxxxxxxxxxxxx
- Date: Sat, 3 Jan 2009 10:26:33 +0100
[Repost from Haiku-doc; soliciting for wider input]
Hi Humdinger,
I thought about your proposal and I would like to suggest an
alternative workflow, which I have some experience with.
[sorry by the way for this late response, I know how frustrating it is
when you want to move forward with something and you depend on others
to actually progress. I blame too much partying]
SOURCE FORMAT
First of all, the source format. There was some discussion on the base
format of HTML. One of the issues was that it supposedly is bad for
print. Another issue is that HTML is very free flow when it comes to
formatting. Even though in recently the separation of formatting and
structure has increased due to CSS, HTML is still to flexible which
would lead to minor inconsistencies in the documentation.
Docbook is an XML based markup language for documentation. It is
apparently used to write books in, but it is mostly known for its use
in open source documentation. For example, see the user guide for
Konqueror[1] in HTML and the Docbook source[2]. The major advantage is
that as a writer you can focus on content. There is a fixed set of
mark up elements that everyone will use. This will lead to consistency
in structure.
To turn the output into HTML, a man page, or even PDF, we can use
libxslt and libxml and the standard docbook stylesheets[3] or perhaps
even port KDE's meinproc[4] which has a considerable easier syntax.
The stylesheets we use are standardized and as such do exactly what we
want. We can tweak the output by tweaking CSS or even the XSLT
stylesheets.
To do for this sollution:
- Convert the user guide from html to docbook
- Write a CSS to tweak the output
Note that the UI guidelines[5] currently are in docbook and that the
build system even supports automagically converting them to HTML.
HOW TO TECHNICALLY TRANSLATE
Now the second phase is how to translate the documentation. First of
all, unless the documentation is absolutely not a moving target, yes,
translating the raw docbook or in your proposal html will work, but in
reality, well, I don't think it will. Now what we can do is find an
intermediate format. This intermediate format needs a few qualities:
1. It should be easily converted to and from the source
2. It should break up the source in chunks so that changes can be
tracked more specifically
3. It should be easily kept up to date with changes in the source.
4. The format should be specifically geared towards translations. We
don't want translators worry about docbook or html.
Now the intermediate format I want to propose is the gettext
format[6]. While gettext is geared towards app translations, its tools
are very good for what we want. The source template is a POT file, we
generate this file from the source docbook. Example pot from the
konqueror manual[7]. From the pot templates we make a po translation.
If there are changes in the original docbook (which are in turn also
in the pot file), we merge these in the translated po with the
msgmerge[8]. Have a look at a translated file of konqueror [9]. If you
search for 'fuzzy', you will see a string which was changed in the
original. A fuzzy is a hint at a translator that he or she should have
a look and update the string. Also, if there would have been new
paragraphs, or paragraphs deleted, these things would be signaled and
added to the file.
The missing component is the conversion from docbook to pot, and from
po file to translated docbook. KDE has created the po2xml (and
xml2pot) tool for that[10]. This should have to be ported for our
purposes. In my experiences it worked years ago, and I imagine that
through time only more kinks have been worked out.
LOGISTICS OF TRANSLATION
The final step is the logistics of the translation. You identified
three issues in your previous mails:
1. How to translate the documentation. In your suggestion, translating
the raw HTML/Docbook
2. How to keep the documentation up to date. In your suggestion, using
diffs and reminder files.
3. How to get translators to submit translations. We identified two
options: using the mailing list or dev.haiku-os.org.
Now on the first thing, the suggestion above takes care of how to, and
what to translate. The major advantage of translating po files is that
it is a translator specific file, without many of the technicalities
of HTML or docbook. Even though it has a learning curve, I think it
will be easier. Even if we in the future might use this format to
translate the applications and the system as well.
The second issue, keeping things up to date, would be very much
automated with the suggested process. msgmerge would do this
automatically, it would signal new paragraphs, deleted ones, and ones
with changes.
The final issue, how to submit translations, is a final thing I want
to comment on. Since a part of the process can be automated, which
means that whenever changes have been made to the original
documentation, these can be forwarded to the translated po files, it
would be easiest if translators have continuous access to their
translations. I'd say, let's keep translations in a separate
repository, a mercurial repository hosted on repos.haiku-os.org. As
I'm writing this, I'd say this is currently the least of the issues to
be worked out, so let's keep that until later.
CLOSING REMARKS
As a closing remark I would say this is a vision I think would work
for several reasons. First of all, it provides an easy format for
documentation writers, who don't have to worry about markup. Secondly,
it provides a easy format for translators, who don't have to worry
about the internals of docbook or html. Thirdly it will provide a way
to keep translations up to date without too much of a hassle.
Finally, I do not want to force any workflow on you. If you do decide
you want to try this one out, I will offer to free up time in the
coming two months to work this out with you, so that eventually you
are able to steer this process yourself.
Anyway, thanks for your enthousiasm. Let's get some user documentation!
N.
[1] http://docs.kde.org/stable/en/kdebase-apps/konqueror/index.html
[2] http://websvn.kde.org/trunk/KDE/kdebase/apps/doc/konqueror/ Note
that this is a split up docbook file. It is very much possible to keep
it in one file, but alas.
[3] http://www.docbook.org/
[4] http://websvn.kde.org/trunk/KDE/kdelibs/kdoctools/
[5]
http://dev.haiku-os.org/browser/haiku/trunk/src/documentation/uiguidelines/HaikuHIG.xml
[6] http://en.wikipedia.org/wiki/Gettext
[7]
http://websvn.kde.org/trunk/l10n-kde4/templates/docmessages/kdebase-apps/konqueror_filemanager.pot?view=markup
[8] http://www.gnu.org/software/gettext/manual/gettext.html#msgmerge-Invocation
[9]
http://websvn.kde.org/trunk/l10n-kde4/nl/docmessages/kdebase-apps/konqueror_filemanager.po?view=markup
[10] http://websvn.kde.org/trunk/KDE/kdesdk/poxml/
Other related posts:
