Translations as part of DOcumentation for Open Source Appropriate Technology

Razi Masri is doing great things with documentation for the hexayurt and more generally for open source appropriate technology.

Over twitter, I suggested "translation should be considered early in the process". Pressed for details, I said "format should not get in the way, and help should be easy to get and give".

Now, that's twitter and 140 characters or less, so let me expand.

It's fuzzy but, hey, that's what it is at this point, at least for me!

1. Software is run by computers, who read computer code and make it do things. Hardware is built by people, who read the documentation and make physical objects. For us, documentation is our code. You teach me how to tie a shoelace and that makes me free.

2. There's lots of experience with translation, and many tools. I know what I know, which means you can help with what you know, and connect the networks of people working on this. The job is not done, and it's important.

Most of my experience is here. I have more questions than answers, but we'll find out with practice and collaboration. Maybe we need to think of documentation and translation as a tool or set of tools that need to be documented themselves.

3. Documentation is text (lightly or heavily formatted), annotated images, and video with subtitles and voice. Out of all that, text is what's touched by the translators. It is created and then recreated when the designs evolve.

4. In the end, access to that text is vital for the translator.

Hardest access comes in the shape of heavily formatted PDFs such as SCIM. Wikis such as appropedia are easier and have their advantages for cooperation, but you need to have a username and a password, and learn some syntax. Even easier to use is piratepad.net, where you just write away, though of course it has limitations.

Are there tools that decouple format from content? I've used http://translate.google.com/toolkit and it's good for some things. You need to log in to google, I think.

Images should have no text, and that's relatively easy. But what about diagrams?

Subtitles should be separate from the video itself. No problem with that.

5. Translators need help.

In my experience, typing away on a piratepad is pure joy, because you have the encouragement that comes from seeing other people typing away in parallel, you can chunk out the work flexibly as you go along (always finding something easy is a must!), and you can swap help by typing directly in the edit window, or in the conversation window.

Google's translation toolkit divides sentences up nicely, keeps format and links, and can even suggest an automatic translation. There's the possibility to use or even create glossaries, which is an important tool for technical translations - and technical translations is what we do.

6. I don't think we're done yet, at all!