… or a new project on Launchpad was born.
On Friday, 20 April 2012, after the release of Mahara 1.5 had been out of the way successfully, we started to have another look at offering the Mahara user manual for translators to work with. I will write more on producing the manual at a later point.
Sphinx, the software we use for the documentation, allows for internationalization. It is also quite easy to generate the translation files. All you need is a one-line command in which to specify the source and the output directory:
$ sphinx-build -b gettext source potfiles
It took a couple of minutes until all files were processed and pot files generated that translators need. That was the easy part. What we haven’t found out yet is what to do with screenshots that should also be translated. The Sphinx documentation doesn’t mention them at all and my post in the Sphinx discussion group hasn’t resulted in any replies so far. Probably, because Sphinx is most often used for code documentation and the code examples wouldn’t need to be translated. 😉
Focusing on the actual text for the moment, my colleague Richard, who also works on the Mahara project, convinced me that it would be the best to use the POT files, even if we haven’t figured out the screenshot translations yet, instead of the translators working with the original files and translating those. The latter would basically mean that the English translation would be forked as anything can be changed in it. Whereas if the pot files are used, updates can be made more easily and the translators are spared most of the code and really only see the strings.
In order not to confuse the documentation translations with the actual Mahara translations, we set up a new project on Launchpad and called it Mahara user manual. 😉 Richard helped me with the initial setup linking one of our existing Mahara groups and thus making some default settings which got us off the ground more quickly. In the beginning, we only set up Launchpad for the translations, but while playing around with the setup, I also activated additional features. I continued the setup yesterday and now the Mahara user manual project has:
- bug and feature tracker
- space for questions
- translations ready to go
- downloadable files
- milestones and releases
(The screenshot says that the project was created on 19 April 2012, but that’s UTC and not NZ time. 😉 So It really was on 20 April 2012.)
I also officially released the 2 existing versions of the manual: 1.4 and 1.5. I can still update the manual whenever I have time, push my changes to the server and update the documentation to Read the Docs, the service where we publish the manual. But in case some people do want to work with the PDF or Epub versions, I might put those files up for download in intervals. Of course, they can always be accessed on the download page for the manual on Read the Docs. Furthermore, this gives me a snapshot of the manual at these times.
There are still a few things that need to be looked into. Chief among them:
- integration of localized screenshots
- automatic creation of the POT files
- setting up the localized directories and the translation export to git
Still a bit of work, but we are getting there.
If you are a user of the Mahara manual and find things:
- that you would like to see added
- that are missing
- that are incorrect
- that are explained too difficult
- that need another screenshot
… or anything else you’d like to say, please head over to the Launchpad page and leave a bug or wishlist report or ask a question.
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.