|
|
| (5 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| | __TOC__ | | __TOC__ |
| | + | |
| | | | |
| | = OpenStack Document Translation Guide = | | = 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. | + | OpenStack uses Zanata as translation server to manage translations. OpenStack Manuals are in DocBook and RST format. We slice the documents into short statements, then use the translatoin server to manage the translation process, and finally converge the translated content into a new copy of DocBook or RST, 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. | | 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 [http://www.transifex.com/ Transifex].
| + | == As translator or reviewer == |
| − | | + | Set yourself up as translator as explained in the [[i18n|i18n team page]]. |
| − | == Contribute as a translator == | |
| − | As a translator, you can contribute to the translations.
| |
| − | | |
| − | * Step 1. Go to openstack [https://www.transifex.com/projects/p/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 [https://www.transifex.com/projects/p/openstack/ 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 [https://www.transifex.com/projects/p/openstack-manuals-i18n/ 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 == | | == 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:
| |
| | | | |
| | + | You can follow the below steps to generate the translated HTML and PDF documents if you want. Just go to the repository that you want to review and run |
| | <pre><nowiki> | | <pre><nowiki> |
| − | (sudo) easy_install --upgrade transifex-client | + | tox -e checklang |
| | </nowiki></pre> | | </nowiki></pre> |
| | | | |
| − | | + | Translations are imported every day into our repositories. The file `doc-tools-check-languages.conf` in a repository documents which manuals get built for which languages. |
| − | Edit the configuration file in your home folder "~/.transifexrc" to include these information:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | [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
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | * Step 1. Check out the sources from Git repository by:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | git clone https://github.com/openstack/openstack-manuals.git
| |
| − | </nowiki></pre>
| |
| − | | |
| − | 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:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | tx pull -f -l [language]
| |
| − | </nowiki></pre>
| |
| − | | |
| − | e.g.
| |
| − | | |
| − | <pre><nowiki>
| |
| − | tx pull -f -l zh_CN
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | If you only want to check out the latest translation for a specific book, use the command:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | tx pull -f -l [language] -r openstack-manuals-i18n.[foldername]
| |
| − | </nowiki></pre>
| |
| − | | |
| − | e.g.
| |
| − | | |
| − | <pre><nowiki>
| |
| − | tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | * Step 3. Merge the translation segment back to DocBook by a Python script:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | ./tools/generatedocbook -l [language] -b [book_name]
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | e.g.
| |
| − | | |
| − | <pre><nowiki>
| |
| − | ./tools/generatedocbook -l zh_CN -b api-quick-start
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | After running this command, a translated docbook will be generated at "openstack-manuals-i18n/generated/[language]/"
| |
| − | | |
| − | Note:
| |
| − | # 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.
| |
| − | # The Python script requires xml2po installed. If you don't have xml2po installed, use below command:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | sudo apt-get install gnome-doc-utils
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | * Step 4. Generate PDF and HTML document
| |
| − | | |
| − | Go to folder "openstack-manuals-i18n/generated/[language]/[bookname]", and run below command:
| |
| − | | |
| − | <pre><nowiki>
| |
| − | mvn generate-sources
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | 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:
| |
| − | | |
| − | # visit the resources page for Spanish: https://www.transifex.com/projects/p/openstack/language/es/
| |
| − | # click on the resource you are interested in
| |
| − | # click "Download for use" and save the file
| |
| − | # Edit the file you downloaded, changing the to say "es_MX" instead of "es" and "Spanish (Mexico)" instead of "Spanish" wherever you find it
| |
| − | # visit the resources page for Spanish (Mexico): https://www.transifex.com/projects/p/openstack/language/es/
| |
| − | # click on the resource you are interested in
| |
| − | # 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
| |
| − | # 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
| |
| − | # the skip option avoids erroring out when there are languages with no translations
| |
| | | | |
| | ---- | | ---- |
| | [[Category:Documentation]] | | [[Category:Documentation]] |
| | [[Category:I18n]] | | [[Category:I18n]] |
OpenStack uses Zanata as translation server to manage translations. OpenStack Manuals are in DocBook and RST format. We slice the documents into short statements, then use the translatoin server to manage the translation process, and finally converge the translated content into a new copy of DocBook or RST, 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.
You can follow the below steps to generate the translated HTML and PDF documents if you want. Just go to the repository that you want to review and run
Translations are imported every day into our repositories. The file `doc-tools-check-languages.conf` in a repository documents which manuals get built for which languages.
