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!

3 comentarios:

  1. Extremely helpful. I have begun to think of what are best practices.
    Modularisation with awareness is key I think. None of the images or text should be created in the end document. They should be brought into the document from external sources. People are aware of the needs of the other modules and the end document and take that into consideration when producing their part. I think translation fits well into this framework.

    I did have dinner with some people that suggesteded I need to document the setting up of the project, the act of documenting a project and why not document translation as well.

  2. Thanks!

    More comments.

    1) Going back to software, I need to look at how people are doing things at Mozilla and LibreOffice, of which I have a vague awareness but no deep links.

    As users, what we see is menu options that are translated, and when a new version of the software comes out only a few options are added or changed.

    So their chunks of text are probably in some kind of table, with a column for each language.

    2) I intend to help with http://opensourceecology.org/wiki/CEB_Press/Manufacturing_Instructions, and that will probably happen on a page-by-page basis. Or maybe, within a page, on a section-by-section basis.

    OSE is churning out documentation pretty fast these weeks, and they intend to have finished 4 of their 50 tools before the end of December. So that should serve as a good practice bed for translation.

  3. http://www-archive.mozilla.org/docs/refList/i18n/ Internationalization and localization by Mozilla. Something to learn from these folks?