Revision as of 16:14, 8 October 2015

• • The page is out of date, and need to be revised.

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.

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

Note:

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

ItsTool Conversion

This section tracks the status of the conversion from xml2po to itstool for managing the extraction of POT files from DocBook and the merging of PO files back into DocBook. These are the steps handled by the generatepot and generatedocbook scripts, respectively. Currently, these scripts import xml2po and change some internals of how xml2po works to accomplish some custom behavior. This has a few problems:

• Digging into xml2po's internals is not officially supported, and could break if xml2po ever saw development again.
• xml2po is deprecated, and hasn't had active development in years.
• xml2po has known issues, particularly with namespaces, that aren't likely to ever be fixed.

itstool was developed as the successor to xml2po, by the person who acccidentally became the de facto maintainer of xml2po. Whereas xml2po uses custom code to determine how to split XML into PO messages, itstool tool determines everything using rules from the W3C Internationalization Tag Set (ITS): http://www.w3.org/TR/its20/

Things to check:

• This should have no effect on the Transifex workflow, as Transifex is just working with the POT files we provide using

our scripts. But make sure there aren't problems.

• Verify that the test and build machines that run the i18n scripts have itstool available, preferably at least 2.0.1.

Steps:

• Get itstool on http://pypi.openstack.org so that it can get deployed on infrastructure server.
• Develop ITS rules that yield similar results to custom xml2po code.
• Rewrite generatepot and generatedocbook as simple wrappers around itstool using custom ITS.
• Put new generatepot and generatedocbook into openstack-doc-tools.
• Consider updating infra structure scripts so that translations are done via tox calls
• Switch openstack-manuals to new tools.
• Switch api-site to new tools.
• Switch operations-guide to new tools.
• For bonus points, look for places where some local rules can save translators a lot of effort. The auto-generated config reference tables could have local rules to make the left column untranslatable, removing thousands of messages from the POT files.

Preliminary work: https://review.openstack.org/#/c/90766/