[Localization] [Translate-devel] Translating the manuals?

[Clytie Siddall]

Thanks very much for your ideas, Friedel: I've forwarded them to the Deb18n and OLPC Loc. lists. :)

On 27/03/2010, at 1:31 AM, F Wolff wrote:

> Hallo Clytie, everybody
> (I'm not putting all the lists in CC, as I'm not subscribed, and not
> sure how relevant everything is to everybody).
> 
> I only have a few loose thoughts.
> 
> 
>> I'd be interested to see suggestions from translators, coordinators
>> and the Pootle/Translate-Toolkit devs on what we really need to make
>> doc translations effective and sustainable. Can we simplify or build
>> on the po4a/Translate-Toolkit/Pootle process? Can we integrate other
>> existing XLIFF tools? What works for you? What would work better?
> 
> I haven't personally done a lot of translation of documents for FOSS
> projects - it simply hasn't been my priority yet for almost any project
> I contribute to while GUI translations are usually far behind. I often
> translate what I use, and I honestly don't use the docs of most software
> a lot.

I'd have to agree with this. App strings come first, and when you're short of resources, doc files don't make it to the top of the list. I've only ended up doing doc files because someone has specifically requested I do so. I've also contributed translated webpages and wikipages, but as I said, I'm concerned about their updateability.
> 
> I think there are a few easy (and obvious) answers, but with several
> aspects outstanding that will have to continue thinking about.
> 
> A big issue for me is access. You mention version control and Pootle as
> means of exposing document translation. If people don't find it easily,
> they will probably translate something else which they can find easily.
> Some websites that I have translated were those where there is a single
> PO file easily available.

Absolutely. For me, if a file is on Pootle, I'll probably translate it, just because it's staring me in the face. I don't have time to go hunting for other files.
> 
> Secondly file formats, which for me is partly an issue of access. If I
> can't use my preferred translation tool, I'll probably just translate
> something else. I agree with Chris that gettext made things easy enough
> to some extent in software l10n.  All documentation is authored in
> monolingual formats not designed for translation (which is fine!) which
> means we have a few issues to solve if we want to translate them.  There
> is a bit of a write-up on the wiki about monolingual formats and
> translating them:
> http://translate.sourceforge.net/wiki/guide/monolingual
> (Of course it also applies to monolingual files for GUI translations,
> not just docs.)

That's a useful summary. At this point, either we go with conversion to standard translation formats, so we can use our current workflow, or we raise awareness of other tools and methods, also creating them where necessary. I think most translators prefer the former, and if we can come up with a good XLIFF-based workflow, we could go on using a standard translation editor, while most of the meta-data and conversion operations could occur behind the scenes.
> 
> But then there is another issue: we need to start writing documentation
> with translation in mind.  Just as we petition programmers to use good
> i18n practices such as variables, comments, and review of the source
> text, we need to do the same with documentation authors. And yes, time
> is always a problem, and documentation is not always written as the
> primary activity that someone is contributing to a FOSS project, so
> giving extra demands on them might not have the desired outcome.
> However, the quality of the source text is an issue. If the quality is
> good, they are also more likely to be stable, in other words, your
> translation might stay relevant for a longer time, also meaning that
> updates should take less time.

Good point.
> 
> Documentation is also a bit different in the sense that incompletely
> translated documentation is probably more bothersome than a partially
> translated GUI - I guess some people might disagree.

If you don't read the original language at all, especially if you can't even recognize its characters, then even one sentence translated is probably better than none.

I'm wondering about tagging doc files with version numbers, so each sentence or paragraph translated can have the version in brackets after it, if necessary. It would work well with XLIFF. In most cases, the tag would only have to be applied to the whole file, but it would also help with partly-updated files. For example:

"Application documentation, version 2.0.5. Last updated: original text 2010-03-21; translation 2009-05-17.
...

"You can use this program to annoy your dog. [v.2.0.2]
"Note: annoying your dog can cause unintended consequences, currently untested. [v.2.0.3]"

The reader can now read most of the information in the translated document, but realizes s/he also needs to check the original docs for later changes (2.0.3 - 2.0.5), including details about how much bleeding you can do after annoying your dog.

"Last updated" details at the bottom of a webpage also tend to be missed by impatient readers. We need a more obvious header.
> 
> The upsides are that translating the documentation might give you a
> better understanding of the software, which can improve your GUI
> translation. For web stuff it can improve the search engine ranking in
> your language, leading to more exposure, etc.
> 
> Just some thoughts while busy with a lot of other things...

It's a good start, thanks. :)

from Clytie 

Vietnamese Free Software Translation Team