|
|
| Line 1: |
Line 1: |
| | __TOC__ | | __TOC__ |
| | | | |
| − | ** The page is out of date, and need to be revised.
| |
| | | | |
| | = 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:
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | (sudo) easy_install --upgrade transifex-client
| |
| − | </nowiki></pre>
| |
| − |
| |
| − |
| |
| − | 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>
| |
| − |
| |
| − | Note:
| |
| − | # If <code>msgfmt command not found</code> error
| |
| | | | |
| | + | 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 apt-get install gettext
| + | 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. |
| − | * 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
| |
| − | | |
| − | == 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/
| |
| − | | |
| − | | |
| | | | |
| | ---- | | ---- |
| | [[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.
