Jump to: navigation, search

Documentation/Translation

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-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"

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 resource list of openstack-manuals
  • Step 2. Select a resource you want to translate, the available languages will be listed.
  • Step 3. If your favorite language is not there, click the link "Add new translation" at the top right corner of the available language list.
  • Step 4. Select your favorite language, and click "Translation online". You will be able to start the translation now.

Glossary

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:

 [https://www.transifex.com]
 hostname = https://www.transifex.com
 password = your_password
 token = 
 username = your_user_name
 
 [https://www.transifex.net]
 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]

e.g.

 
 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]

e.g.

 
 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]


e.g.

 ./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]/"

Note:

  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


  • 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.