Skip to content

Instantly share code, notes, and snippets.

@daisy-ycguo

daisy-ycguo/OS_doc_translation_guide.wiki

Created July 3, 2012 02:26
Show Gist options
  • Save daisy-ycguo/3037139 to your computer and use it in GitHub Desktop.
Save daisy-ycguo/3037139 to your computer and use it in GitHub Desktop.
Download ZIP
OpenStack Document Translation Guide
Raw
OS_doc_translation_guide.wiki

Table of Contents

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 (http://www.transifex.com/).

Contribute as a translator

As a translator, you can contribute to the translations.

Then you can start your translation.

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 (https://www.transifex.com/projects/p/openstack-manuals-i18n/)
  • 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"

Contribute as a coordinator for a certain language

As a coordinator for a certain language, you need to manage the translations for this language, and generate HTML and PDF document if needed.

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

Task 1. Check out the latest translation for this language, and generate HTML and PDF document

step 1. Check out the sources from Git repository by: 

 git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.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.

Contribute as project manager

As a project manager, you need to manage the all the resources, all the translations, and the releases. 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.net]
 hostname = https://www.transifex.com
 password = your_password
 token = 
 username = your_user_name

Task 1. slice the document into short statements and upload to Transifex when a new document is added

step 1. Check out the sources from Git repository by: 

 git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git

After this step, the source code of OpenStack Manuals will be downloaded to your local disk. Make sure there is a .tx folder in the root of the repository. Or else, you will need to initialize the Transifex project by: 

 tx init

step 2. Slice the document by a Python script: 

 ./tools/generatepot [foldername]

e.g 

 ./tools/generatepot openstack-compute-admin

After this step, a PO template will be generated in folder "doc/src/docbkx/[foldername]/locale"

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 3. Create a new resource in Transifex using your new local PO template 

 tx set --auto-local -r openstack-manuals-i18n.[foldername] 'doc/src/docbkx/[foldername]/locale/<lang>.po' --source-lang en --source-file doc/src/docbkx/[foldername]/locale/[foldername].pot --execute

for example, if you want to upload the PO template for openstack-api-programming, you need to type following command: 

 tx set --auto-local -r openstack-manuals-i18n.openstack-api-programming 'doc/src/docbkx/openstack-api-programming/locale/<lang>.po' --source-lang en --source-file doc/src/docbkx/openstack-api-programming/locale/openstack-api-programming.pot --execute

step 4. Push the new resource to Transifex by: 

 tx push -s -r openstack-manuals-i18n.[foldername]

step 5. Push your changes to Git repository by: 

 git add .
 git commit -a -m 'add new PO template'
 git review

Task 2. Update a Transifex resource if a document is updated

step 1. Generate a new PO template by the Python script: 

 ./tools/generatepot [foldername]

e.g 

 ./tools/generatepot openstack-compute-admin

After this step, a new PO template will be generated in folder "doc/src/docbkx/[foldername]/locale"

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 2. Push the update PO template to Transifex by 

 tx push -s -r openstack-manuals-i18n.[foldername]

e.g. 

 tx push -s -r openstack-manuals-i18n.api-quick-start

step 3. Get the update PO files from Transifex by 

 tx pull -r openstack-manuals-i18n.[foldername]

e.g. 

 tx pull -r openstack-manuals-i18n.api-quick-start

step 4. Push your changes to Git repository by: 

 git add .
 git commit -a -m 'update sources'
 git review

Task 3. Check out all the translations from Transifex and update to Git repository when a release is made

step 1. Check out the sources from Git repository by: 

 git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git

After this step, the source code of OpenStack Manuals will be downloaded to your local disk. Make sure there is a .tx folder in the root of the repository. Or else, you will need to initialize the Transifex project by: 

 tx init

step 2. Check out the latest translation from Transifex by: 

 tx pull -a -f

step 3. Push your changes to Git repository by: 

 git add .
 git commit -a -m 'add new PO template'
 git review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment