Documentation proposal

[Brian J. Tarricone]

Mike Massonnet wrote:
> 2009/5/4 Brian J. Tarricone <bjt23 at cornell.edu>:
>> Related to synchronisation, the main benefit is that it's easier to tell
>> what's changed -- that is, if I go and change one sentence in the English
>> docs, rebuilding the .po files will make it very easy for the translator to
>> figure out what I changed without having to read through the entire doc.
> 
> Sync the doc allows it to be mixed with english texts. Figuring that
> syncing the translated doc is not possible, one good way would be to
> have a trunk/ that is an in-progress documentation and english-only.
> Than existing branches would exist for stable docs for specific
> versions of the components and are freezed, and those would be allowed
> to contain translations.

I hesitate to weigh in with too strong an opinion here, since I've never 
translated anything in my life, but I'll throw this out anyway: this 
just seems counterintuitive to me.

For the translation of strings in a program, .po files seem to be a good 
choice to me.  Most UI strings are short and standalone[1], and are 
often repeated (so having one translation for all the repeats is a good 
thing).

For documentation, the work to be translated is the *entire work*. 
Context is *everything* here, and breaking up the text into smaller 
sections to be translated might make you *feel* like it's easier to 
translate ("oh, I can do a little bit here, a little bit there, and not 
all at once"), but in reality, it seems like the .po file model would 
result in a lower-quality translation than just taking the document as a 
whole and translating it.

> It is easy to let the translator know which documentations can be
> translated. I guess that's the best option I can come up with, that is
> easy and doesn't let the doc being provided with different locales
> while most of them could be out of sync. Very very annoying.
>

Frankly this seems like the *worst* reason to use a translation system. 
  If making the docs discoverable is a problem, there are much better 
ways to solve it than picking a translation model that lumps the docs 
translations in with the rest of the normal translator's workflow.

>> How do translators deal with the website translations?  Does that seem to
>> work well?  Maybe we should use that as a model?
> 
> The website, well a pita of course.

Ah, that's a shame.  Pass on that model, then ^_~.

Also as a bit of a semi-unrelated aside... I wonder if we're doing the 
right thing in trying to push docs translation on our existing group of 
translators.  For some of them, sure, it's fine, but translating UI 
strings and translating documentation prose requires a bit of a 
different language skill set.  (In a similar way, writing English UI 
strings requires a different language skill set than writing English 
docs.)  Of course, we don't want to turn down help, especially if help 
is otherwise unavailable...

	-b

[1] Of course, even with UI strings, translators sometimes have problems 
with context!