John Devereux wrote:
But I would really appreciate any insights anyone may have.
I've got some experience on this. I'm sure my way is not optimal, but at
least it is an experience.
First thing to remember is that I started the ConTeXt project many years
(5???) ago and the program *and* its documentation have evolved a lot
since then.
The other thing is that I didn't expect to have to deal with
translations. The documentation (and the instrument the manual is for)
were both supposed to exist in English only. Yeah. Sure. (We don't do
consumer electronics, so regulations are a bit different than for stuff
you buy in a shop.)
So over these years I've dealt with repeating "please send us the manual
as Word file for translation" queries. Every time I've explained in
words of one syllable that there's is and will not be a Word file, that
the distributed manual file has origins in a totally different system.
We stopped using Word when the file grew so big that Word just couldn't
cope and when most of the figures to be included were pdf anyway and
thus easily incorporated into ConTeXt files.
I always offer to send the potential translators the files and the
editing instructions and say that I can do a pdf out of the translated
files any time, for example after each chapter. (BTW, if you'd like my
editing instructions, I have them somewhere in rtf format.)
The reactions to the above information vary. A South American
professional translator took the files without whining and turned in the
translated Spanish text with only *two* messed up codes - which is a lot
less of a mess than I do when editing. The French gave up directly; they
supposedly have a Word version of their own of the manual and so do the
Poles. Three other languages were written in Word (or similar) and I had
all the fun in cutting-and-pasting the text into the ConTeXt files.
Italian was first done with cut-and-paste method, but then needed so
much work that to my surprise they edited the ConTeXt files for me with
a very good result - that's probably the most accurate translation of
the whole lot.
The Russian version of our manual is in the works. They wanted to do it
all by themselves, but I haven't heard anything since I debugged their
last file (encoding problem, Win-cyrillic to UTF). I hope that means
everything is under control there... They are basically working on a
pared-down duplicate system so we can easily exchange files.
I should add that except for the South American translator and the
Russians, the other persons are not IT people, nerds or not necessarily
even that computer litterate (if their usage of Word is anything to go
by....). If your translators are used to structural coding (html, for
example) and especially if they already use suitable editors, you'll
have a lot less problems.
Then the practical aspect. What I had from the beginning is a system
where each chapter of the manual is a file of its own - makes it much
easier to handle. Most of the formatting and setups is in the main file,
so the chapters just contain list of figures and then the text itself.
This makes them much easier to edit and handle.
When I started getting the languages, I made subdirectories for them,
one per language. This is where I put the tex files for that language +
all the figures that have translated text in them; ConTeXt will look
first in the same directory and then further afield, so if there's a
translated figure, it will get used. If not, the figures of the English
manual are used. That way I don't have to repeat anything that has no
text in it - and the manuals compile from the beginning, first English
everywhere and then little by little with translations.
I have a main format file for each language. This is because of the
language settings (hyphenation, labels), but also because the English
manual is letter size and most translators prefer A4. Sometimes also one
language only needs small adjustments (like we have no index in
Italian), so I find it easier to keep all the layout stuff separate one
language from another. However, the main layout had already been the
same for two years when the first translation came along, otherwise I
might move some information (like heading formatting) into a shared
formatting/setup/layout file for easier changes.
So, how do I keep all of this up to date?
I don't. Fully. But if I could devote most of my working hours into
that, I maybe could... Won't happen this decade, I think.
One thing that helps is version control (SVN) that keeps all the files
and I try to document very carefully in the log files what I've done. As
I usually check in all the files before leaving work, I still remember
what was done and the log is reasonably good. SVN also means that I can
diff with an earlier version of the file and see what changes were made,
this is also handy.
Another thing is that any changes I can make myself, I'll do all over
the manuals at one go. For example we had a small mistake in a protocol
specification - fixing that didn't require much understanding of the
language, just careful copying and pasting from another spot in the same
file. Minor fixes in German and Swedish can also be done in-house.
Our manuals also have version numbers and unless it is revised, any
translation keeps its original version number. For example the current
English version is 1.64, but I'm doing cut-and-paste on an old
translation that's version 1.51. On the front page of each translated
manual we now have a disclaimer saying that if information in that
manual and the English version conflicts, the English is considered
correct. [My ongoing cut-and-paste project is so bad that even with a
three-word-command of the language in question I can tell that it is a
sorry translation... so the old version number isn't that much of a
hinder anyway...]
I assume that the only way to keep an evolving manual on track is
careful logging of what was done, by whom and when. If translations
involve a lot of people, it'll probably help to have clear instructions
on what to do when there are changes. When the master language is fixed,
you need to know who will log the changes and make sure that the
translations are fixed accordingly and how that's done - by sending a
new file to translator, by telling them to check them out or by having
them send those three lines to you by email so you can cut-and-paste
them into your text.
But it is definitely worth the while to figure things out so that
anything that doesn't need translation, only exists once and is used by
all languages.
One very small thing that I came up with by the third translation
language is that my files are named similarly, but with the language
abbreviation first. So I have intro.tex (English), se-intro.tex
(Swedish), es-intro.tex (Spanish) etc.
First I thought this wasn't necessary as the files are in different
directories (root directory intro.tex vs. Swedish/se-intro.tex vs.
Spanish/es-intro.tex), but then I realized that it wasn't actually that
fun to have three intro.tex tabs open in my Scite, couldn't tell fast
which one was which. Occasionally the files also get copied to Desktop
and sent all over by email and unique naming does make it easier to
figure out what went and where.
Just my five cents,
Mari
Finland
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the
Wiki!
maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage : http://www.pragma-ade.nl / http://tex.aanhet.net
archive : https://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___________________________________________________________________________________
