Documentation proposal

[Mike Massonnet]

Jannis Pohlmann wrote:
> On Mon, 04 May 2009 10:55:43 +0200
> Mike Massonnet <mmassonnet at xfce.org> wrote:
> 
>> Jannis Pohlmann wrote:
>>> On Mon, 4 May 2009 10:26:33 +0200
>>> Nick Schermer <nickschermer at gmail.com> wrote:
>>>> The advantage of a hook is that we also have all the translations
>>>> in the docs package and keep them there (if we're going to use
>>>> docbook xml2po kinda stuff, bit harder to write but easier for
>>>> translators to track changes). I'm not sure, but I think if we
>>>> merge all the doc translations, a lot of duplicated strings will
>>>> show up, which makes it easier for translators.
>>> I'm against too complex hooks. I also have the feeling that the good
>>> old gettext translation method is not really suited for continuous
>>> text. IMHO the little syntax overhead you have with reST makes .po
>>> files almost pointless.
>> Of course the po file is not readable, as good as the original file,
>> but the most important thing here is to keep the translation synced
>> with the english text. So unless there isn't a good solution for that
>> without xml2po, I had recommend the use of the po files (even
>> mandatory).
> 
> BTW, we'd have the same copy + synchronization issue with a wiki-based
> solution. I still don't think .po files are the best way to go for
> continuous text like e.g. user guide. The only benefit we get is better
> synchronization. The downside is that translating paragraphs out of
> context (in .po files) is less fun. And we'd still have some of the
> markup in those strings, so why not go with copies right from the
> beginning?
> 
> To emphasize the difference between our usual translations and
> documentation even more: the documentation will contain way more
> text than our applications and libraries. Translating them is a task on
> its own. I doubt that translating the docs will work without dedicated
> documentation translators. I'm not too worried about the
> synchronization if the communication between the documentation people
> works well (and there are clearly defined deadlines for when work on
> the English docs has to be finished).
> 
> The focus should be on having complete and up to date English
> documentation. That's quite a challenge already. 

Well nothing has been settled up for translations via a wiki. Seeing the 
current state of wiki.xfce.org, translations are going in from time to 
time, but than they are left out and get unsynced. For example the FAQ 
has seen new entries, and after a while it gets hard to update the 
translation.

Let's just say that for translations, we need to make it easy. As said, 
po files ain't perfect for documentation -- long strings, or no 
difference between a title and menu entry, etc -- while with the rst 
syntax it feels more natural to translate it and type it. If we take the 
clutter out of the whole translation job, than we will probably see 
translations coming in more often.

Without po files we will miss the sync possibility. Oh, and on a 
sidenote, xsltproc is buggy, I am not able to use it to get back from 
the xml file to the txt file, I had to use another tool (xalan-java 
although there is a C++ implementation but that one doesn't work from 
the arch package), but the whole txt2xml2po2xml2txt works. And that 
would be only necessary if we want to fit with po files to keep the 
translated doc synced. And also for the record, the po files contain 
references to images, which don't need to get translated (hinhin) and 
also get fuzzied when the images are updated. But most of the time, and 
that's IMHO at the po files fault, the translators forget to attach 
screenshots. I guess that's one thing that will be less confusing when 
typing a rst file.

IMHO^W, you are right by saying that po files are wrong. We just need to 
figure out a way to avoid the translations to be left 3 versions behind.

My last 2 cents
Mike