… 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
- announcements
- 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.
Very cool!
Regarding the localization of screenshots, I’d vote for having the originals in Gimp format, with several layers. One of the layers would contain the screenshot itself, while another layer would contain the callouts. We could even have different layers for different kind of callouts (just numbers vs text strings).
This way one just needs to capture the localized screenshot and paste it into Gimp as a new layer in the existing “master” screenshot image. Then we would just need to move the pasted layer to the right place in the layer stack (so the callout layers are placed “above” the screenshot layer) and align thigs a bit. If any of the callouts needed to be translated, selecting the right layer and editing the text labeld would do it.
Given that Gimp is available in Linux, Windows and OSX, this shouldn’t be a blocker for translators 🙂
Later, when “compiling” the manual, we could use xcf2png (part of the xcftools package in Debian/Ubuntu) to create the final .png files from the .xcf originals.
Saludos.
Iñaki.
Hi Iñaki,
Thank you very much for your suggestions. Initially, I thought to use Inkscape (or Gimp) to produce the final images, but it takes way longer than in Shutter where I just put the numbers in and they are incremented automatically. I was not drawing circles and putting numbers in them. As the translated screenshots can have different dimensions, I was not sold on it being more efficient to move these callouts around instead of quickly creating them again.
If you know of an easy way of doing these callouts in Inkscape / Gimp, I’d be happy to revisit this for the 1.6 manual. 🙂 As for the compilation part: Do you know if Sphinx supports xcftools?
I also don’t put any text in the screenshots, just the numbers to avoid too much information. In addition: All important text is displayed as text and not in an image for accessibility reasons.
Some images, like the artefact box are available in SVG format for easy adoption in Inkscape. They are in the images_originals folder in git. 🙂
Hi Kristina,
I’ve found a Gimp fu-script that does (almost) exactly what Shutter does with the callouts. It’s called “Mark Number Circles” (http://registry.gimp.org/node/25086). I’ve hacked it a bit to make the callouts like Shutter (the circle is not fully filled, only the circle line is stroked, plus the callout has a transparent background).
I like Gimp plus this script better than Shutter for 2 reasons:
– Shutter is only available for GNU/Linux (no Windows or Mac OSX version), while Gimp is available in other mainstream OSes (and the script is a plain text file).
– The script creates a new layer for each callout, so you can even move them once they are created (in case you missed the right target or changed your mind later). All the layers are merged when you save the file, though (unless you save the image in the Gimp native format), so you get plain old png, gif, jpg images as usual 🙂
The installation of the script is trivial (just put the file in the right directory) and the usage is super simple too.
Regarding the compilation part and Sphinx support for xcftools, I suspect Sphinx doesn’t have any support for it. But the thing is, we don’t mind 🙂 We just need to make sure we have png (or gir, or jpeg, or whatever image format Sphinx needs/supports) files by the time we execute Sphinx. And this is Makefile’s job 🙂
In fact, the SVG images you mention could be converted to png (gif, jpeg, …) automatically as part of the compilation process, so you wouldn’t even need to convert them by hand every time you edit the original SVG files. In this particular case, instead of using xcftools, we would need ‘convert’ from the ImageMagick utilities.
I can take care of the Makefile modifications if think this is worth it 🙂
Saludos.
Iñaki.
Hello Iñaki,
Thank you very much for looking more into the Gimp plugin. It sounds like a good plan. For the callouts: were it possible to add a white fill to the circle? Otherwise they won’t stand out so well on non-white background or when you need to place the callout over white and grey for example.
If you want to look into creating the Makefile so that SVG and the original layered Gimp files are converted before they make their way into the Sphinx building process, that would be fantastic because I certainly wouldn’t know where to start. 😉
Cheers
Kristina
By the way Kristina,
did you get my ‘merge request’ on gitourious.org with the Makefile changes proposal?
Saludos.
Iñaki.
Mhh. I didn’t. But that might be because I think I’m not the owner. I’ll investigate.
Hi,
By change I found this blog post and I found very interesting. I agree with Iñaki that if we could use a more widespread software such as Gimp it would be better for those who are working on Mac or PC. I will try this weekend Gimp and the plugin Iñaki mentioned earlier, I was looking for something like that for my own callout in my doc for other projects.
So you both made my day today.
Cheers,
-dajan
Sorry for the late reply, dajan. Iñaki tweaked the Gimp script, and he wanted to post it online for everyone to use. It works really well and is easy to use.
Hi Dominique and Kristina,
I have just created a public page at mahara.org (https://mahara.org/view/view.php?id=60234) with the script and all the details on how to use it (and posted about it in the translators group’s thread “User manual and translations”).
Saludos.
Iñaki.
That’s a great demo. 🙂