[Xfce-i18n] Documentation proposal

[Jannis Pohlmann]

On Mon, 04 May 2009 15:09:18 +0200
Mike Massonnet <mmassonnet at xfce.org> wrote:

> 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.

I think the main problem is that the typical .po file workflow does not
apply to documentation. Translating strings in an application means to
translate a small part (usually rather short strings) of something.
Translating documentation means to translate the whole thing. 

IMHO that will only work if the translators work closely together with
the people writing the English documentation. That's why I think it
only makes sense to translate the documentation into a certain language
if there's a dedicated person to do the job and to stay in touch with
the documentation team the whole time. It's *a lot* of work. It's not
just translating another component. 

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce-i18n/attachments/20090504/59462738/attachment.pgp>