Translating Apache CloudStack docs with Transifex

One of the big changes leading to the release of Apache CloudStack 4.0 (ACS) has been converting the existing documentation to docbook XML format. The resulting books are built in various output formats using publican. The entire ACS 4.0 documentation is now in docbook XML format.

All the documentation is located in the /docs directory in the ACS 4.0 source release. Folks who are not Apache committers yet, can write documentation in docbook and submit patches. A good way to contribute is to start working on existing docs bugs (I should follow my own advice sometimes :) ).

One of the benefits of moving to docbook XML and publican is the ability to produce documentation in multiple languages. Publican can define Portable Objects (PO) that build a framework for translation of the original documentation resources. To translate them, ACS uses transifex. While it is possible to provide translation from the command line using the transifex client, the easiest way to get started is to go through the on-line interface of transifex. The following screenshots walk you through this process (click on them to enlarge).

First, create an account on transifex and login

You will be presented with your brand new transifex dashboard, search for CloudStack projects

You will see several CloudStack related projects, pick the one that interests you the most. Most likely the core documentation project , but you can also contribute to the runbook or the UI.

Once you are on the project page, you will see the various languages that are being worked on, as well as the percentage of completion of the translations. There is work to do :). By clicking on resources you will access all the resources that are available for translation. If you have checked out the source code, you will recognize the names of the docbook XML files in /docs/en-US.

Pick a resource that you would like to translate, you will be presented with that resource page. A Add New Translation icon is present on the right, click on it. You will then be able to select the language you want to translate to. Proceed by selecting the translate online button.

A form to enter your translation will be displayed. It is broken up in strings that make up that resource. Enter your translation for each string, save and exit.

You will then be returned to the resource home page and you should see that your translation has been added (i.e your language should be present). Once you return to the project Dashboard if the language your translated to was new, you should see it in the dashboard.

Once a significant portion of the translation is completed, one of the committers ( I volunteer David Nalley :) because he has nothing else to do ) will pull your translations using the transifex client and will build the new book with publican. Let's get translating...