Jump to: navigation, search


OpenStack Document Translation Guide

OpenStack uses Transifex to manage translations. OpenStack Manuals are in DocBook format. We slice the documents into short statements, then use Transifex to manage the translation process, and finally converge the translated content into a new copy of DocBook, which will used to generate HTML and PDF versions.

If you want to contribute to document translation, there are several different roles which you can contribute as.

First of all, you need to register in Transifex.

Contribute as a translator

As a translator, you can contribute to the translations.

  • Step 1. Go to openstack translation site
  • Step 2. Click on the language you prefer.
  • Step 3. Select a resource
  • Step 4. In the pop up window, click "Translate Now"

Then you can start your translation.

Add an available language

If your favorite language is not in the list, do the following steps:

  • Step 1. Go to the openstack project page
  • Step 2. If your favorite language is not there, click the link "Create language" on the top bar, above of the available language list.
  • Step 3. Select your favorite language, and click "Translation online". You will be able to start the translation now.


On the top of translation UI, there is a link to "Glossary", click on it, a glossary page will be opened. You can reference it and edit it.

Contribute as a reviewer

As a review, you can review the translations.

  • Step 1. Go to openstack-manuals translation site
  • Step 2. Click on the language you prefer
  • Step 3. Select a resource
  • Step 4. In the pop up window, click "Translate Now"
  • Step 5. After you review an item, you can click the checkbox at the end of each item line.
  • Step 6. If you don't like the translation, you can supply your suggestion by clicking "suggestions"

Generate documents for a certain language

You can follow the below steps to generate the translated HTML and PDF documents if you want.

In order to easily manage translations, you need to install Transifex Client by:

 (sudo) easy_install --upgrade transifex-client

Edit the configuration file in your home folder "~/.transifexrc" to include these information:

 hostname = https://www.transifex.com
 password = your_password
 token = 
 username = your_user_name
 hostname = https://www.transifex.com
 password = your_password
 token = 
 username = your_user_name

  • Step 1. Check out the sources from Git repository by:
 git clone https://github.com/openstack/openstack-manuals.git

After this step, the source code of OpenStack Manuals will be downloaded to your local disk.

  • Step 2. Check out the latest translation from Transifex by:
 tx pull -f -l [language]


 tx pull -f -l zh_CN

If you only want to check out the latest translation for a specific book, use the command:

 tx pull -f -l [language] -r openstack-manuals-i18n.[foldername]


 tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start

  • Step 3. Merge the translation segment back to DocBook by a Python script:
 ./tools/generatedocbook -l [language] -b [book_name]


 ./tools/generatedocbook -l zh_CN -b api-quick-start

After running this command, a translated docbook will be generated at "openstack-manuals-i18n/generated/[language]/"


  1. The Python script must be run under the root folder of the document project, e.g. openstack-manuals-i18n. Or else, you will get errors.
  2. The Python script requires xml2po installed. If you don't have xml2po installed, use below command:
 sudo apt-get install gnome-doc-utils


  1. If msgfmt command not found error
$ sudo apt-get install gettext

  • Step 4. Generate PDF and HTML document

Go to folder "openstack-manuals-i18n/generated/[language]/[bookname]", and run below command:

 mvn generate-sources

The translated HTML/PDF book will be generated.

Seed the localisation of a new language, using an existing language

For example, if we wanted to start a new localisation of Spanish for Mexico, we first request a new language using the steps above, then we can use the existing Spanish ("es") translations to kick-start our localisation efforts:

  1. visit the resources page for Spanish: https://www.transifex.com/projects/p/openstack/language/es/
  2. click on the resource you are interested in
  3. click "Download for use" and save the file
  4. Edit the file you downloaded, changing the to say "es_MX" instead of "es" and "Spanish (Mexico)" instead of "Spanish" wherever you find it
  5. visit the resources page for Spanish (Mexico): https://www.transifex.com/projects/p/openstack/language/es/
  6. click on the resource you are interested in
  7. Click upload the file, and select the file you modified.

Change the source language

0. Install transifex client

   $ sudo apt-get install transifex-client 

1. Create a new project in Transifex called "nova_new"

2. Create a folder in your local disk called "Translation"

3. Run below command in folder "Translation" to pull all the translations from old project

   tx init --host=https://www.transifex.com
   tx set --auto-remote https://www.transifex.com/projects/p/nova/
   tx pull -s
   tx pull -a

A folder "translations" will be created under "Translation", and it will contain all the po files including "en_US.po", which is the source file.

4. Remove en.po, and rename en_US.po to en.po, and change the header of the new en.po. Pay attention to "Language-Team" and "Language" values.

 msgid ""
 msgstr ""
 "Project-Id-Version: Nova\n"
 "Report-Msgid-Bugs-To: https://bugs.launchpad.net/nova\n"
 "POT-Creation-Date: 2013-08-30 06:06+0000\n"
 "PO-Revision-Date: 2013-08-30 01:46+0000\n"
 "Last-Translator: openstackjenkins <jenkins@openstack.org>\n"
 "Language-Team: English (http://www.transifex.com/projects/p/openstack/language/en/)\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 1.3\n"
 "Language: en\n"
 "Plural-Forms: nplurals=2; plural=(n != 1);\n"

5. Run below command in folder "Translation" to push all the translations to new project

   rm -rf .tx
   tx init --host=https://www.transifex.com
  1. edit .tx/config and add a line "type = PO"
   tx set --auto-local -r nova_new.nova-translations 'nova.nova-translations/<lang>.po' --source-lang en --source-file 'nova.nova-translations/en.po' --execute
   tx push -s -t -f --skip
  1. the skip option avoids erroring out when there are languages with no translations