Mari Voipio <mari.voi...@iki.fi> writes: > 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.
Hi Mari, thank you very much for such a long and detailed answer! Your experience very much reflects how I can see things going. > 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. Is there anything in particular new that you think might help? > 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.) Certainly, if it is convenient, thank you. > 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. 2 out of 7 is not what I was hoping for... I assume these were your agents or similar (rather than "professional" translators)? If so that is how we were hoping to do it too. > 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. Not much chance of that I'm afraid. Although there's no reason I could not tell them to use Scite or similar. I was going to try saving the tex original as .doc - word seems to open it OK - and then saving *their* end product as "encoded text/UTF8". Has anyone tried this? > 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. I was going to have a single environment file, which the translators never see, then a *single* document file. But perhaps separate chapters would be better... My document is not so big, maybe 30 pages of text (plenty of screen captures too). So perhaps my document is like one of your chapters. But there could be several other documents in the pipeline, so am trying to come up with a workable approach. > 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. I think I can do everything with one environment file and some modes. I also have a similarly functioning layout in mind to avoid duplication of common images, with fallbacks and so forth. > 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. Yes, I am already using version control (git). [...] > 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. No "magic bullet" then. > 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. Very true - I have seen this when doing the software part of our project. It's even worse than I have been describing, we actually have to produce the software and manuals for several different vendors, with their own "branding", company logos, splash screens, icons etc. I have had to very carefully think through how to avoid having N_LANGUAGES*N_VENDORS separate copies of *everything* to maintain. The manuals are where everything comes to a head - here we really do need to produce N_LANGUAGES*N_VENDORS versions. I believe Context will be very useful in programmatically generating all the manual variants from a single source tree. > 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. A useful point, thanks. I *was* going to give them the same name. > Just my five cents, Thanks, -- John Devereux ___________________________________________________________________________________ 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 ___________________________________________________________________________________
