[Mono-docs-list] (no subject)

[Johannes Roith]

Hello binhara!
Hello, everybody!

Binhara talked to me lately, about a translation project of the Mono
Handbook to Portuguese as part of the Brasilian Mono community effort.
I'm very happy to see this happen and want to line out and discuss how
this in particular and translation in general should be done.

Here are some thoughts:

* Translation should take place in Mono CVS, as this is probably the
only way to keep track of changes and eventually update the translated
documents later.

* To get started, I will import the content from /html/en to
/html/pg-br. Also Documentation.xml will be copied to
Documentation.pg-br.xml and a new makefile target will be defined.

* The problem however will be to keep the translation in sync and
up2date with the english original. I suggest that the translation is
done based on that import, while it gets out-of-sync with the english
version. When the translation is complete, the directory should just
import new files and carefully integrate the changes to the outdated
files, like described in the next paragraph.

* Content should only be changed or added in the english version, even
by the brazil translators and then translated.

* It must be possible to track all changes in the english files, that
happend since the current translation of a file. To achieve that, I
suggest the following:

	Each file in /html/pg-br should contain an additional meta tag:

	<meta name = "CVS.English.Version" content = "1.2" />

The value would indicate, the CVS revision of the ENGLISH version, that
has been the base for the translation. To keep track of all changes one
would only need to diff that version of the english manual against the
latest english revision and it would then be possible to easily trnslate
all the changes. After that the metatag would be updated.

I know it is some work to maintain those tags, but IMO it is less work
than figuring out *somehow* what things have changed.

I have created a tool, to automatically generate the correct "diff" (the
changes in the english original) for a translated file, though that tool
currently works by calling the online CVS browsing tool.

So, this is just a suggestion, please comment on it, but I don't see any
other way.

* Documentation.pg-br.xml is a pain to maintain - even more than
Documentation.xml. We don't have any differnt way to do it however. All
that can be done to keep things up2date is noting the revision and
eventually diffing the english versions. PAY ATTENTION! Once that file
is out-of-sync with the actual files, how will you be able to resync it?
(Without much work).

Also pay attention to not only translate the descriptions, but also
change the patch from /html/en to /html/pg-br everytime.

* When new files are added, you have to copy them to your tree (When
decided you catch up again) and add the initial CVS revision metatag.

* Translators should not be listed as contributors, except they actually
contribute to the original. They will be honored as Translators in the
browser, by using the tag:

	<meta name = "MonoDoc.Translator"  content = "Your Name" />

Otherwise it might happen, that the Translators names get merged back in
the original.
Translaters also will be honored in the "global" Credits section, even
in the English version.


* This is just a suggested way of doing it, so poeple can comment. I
will probably post additional information later. Also I will copy the
tree as soon as some last organizational changes are made to the
handbook and we can fully concentrate on content.

Let's try to do this as good as possible. Translations are always lot's
of manual work - for translation itself and also for keeping the thing
in sync, but it should be doable if you maintain the metatags correctly
and have enough energy.

Go, go, go!

Johannes