Writing and translating documentation in Debian Edu
16th March 2012
Documentation in Debian Edu is provided in several languages, and it is important to make it both easy to contribute and to keep the translated versions in sync. To do this we have come up with what we believe is a very efficient work flow.
- The documentation is written in a moinmoin wiki (see for example the Squeeze release manual) with support for exporting the content as docbook XML.
- This docbook document is given to po4a to extract a gettext style .pot file with the content, which in turn is used to create .po files with the translated text.
- The .po files are given to translators, and they can always tell which part of the original wiki document is new or changed. They can use their normal translation tools like lokalize or poedit to write the translation. There is even a system in place to handle translated images.
- The translated .po files are combined with the original docbook XML document using po4a to create a translated docbook document.
- The final step is to use all the generated docbook files and create PDF and HTML version of the original and translated documents.
This setup work very well, but have a few issues. The biggest issue is that the docbook support we use in moinmoin is not actively maintained. The docbook support is also buggy, and our build system contain workarounds to make sure the generated docbook is usable despite these bugs.
If you want to have a look at our setup, it is all there in the debian-edu-doc package.