OpenStack documentation has a series of documents for administrators and API users. All these documents need to be translated. The continuous development of documents brings difficulties to the translation management, but the process can be automated with continuous integration. This slide deck introduces the process and the technologies used in the translation management during OpenStack document internationalization. It also includes a demo for creating a Chinese version of manuals.
2. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 2
3. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 3
4. 文档页面
Web Page for Documentation
http://docs.openstack.org
www.openstack.org
5. Challenges of Community Document
Large amount of code Grow quickly
Change frequently Loose coupling
Manage document as code !
www.openstack.org 5
6. Document Process: Design
Blueprints and discussion at Design Summit
Blueprints
Current blueprints found at
https://blueprints.launchpad.net/openstack-manuals
www.openstack.org 6
7. Document Process : Development
Github repositories store admin guides and API
guides
Unit tests with Jenkins
Patch review with Gerrit
www.openstack.org 7
8. Document Process : Bug tracking
Manage bugs through Lanuchpad
Bug logging
Bug triaging
Bug assigning
www.openstack.org 8
9. Document Process : Publishing
Automatically publish with Jenkins
www.openstack.org 9
10. Doc Team Composition
All OpenStack community members
One percenters = OpenStack-doc-core
Badge Wearers
AT&T
IBM
Nebula
Nicira
Nimbis Services
Nuage
Rackspace
RedHat
www.openstack.org 10
11. Statics
20+ Compute Extensions documented at api.openstack.org
66% Site visitors stay instead of leaving
100 Doc patches and reviews a month
726 Configuration options : 467 for nova.conf, 259 for swift conf
files
10,000 Unique visitors a week at docs.openstack.org
www.openstack.org 11
12. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 12
13. Challenges of Document Translation
Large amount of code Grow quickly
Change frequently Loose coupling
Manage document translation as code string translation!
www.openstack.org 13
14. Translation Process : Slicing
Slice DocBook into string segment with a Python script, and
generate a PO template
./tools/generatepot openstack-compute-admin
www.openstack.org 14
15. Translation Process : Translating
Manage translation by Transifex
Translation project & resources
Translation memory
Glossary
www.openstack.org 15
16. Translation Process : Merging
Merge the translated string into Docbook with a python script.
./tools/generatedocbook -l zh_CN -b openstack-compute-admin
www.openstack.org 16
17. Translation Process : Uploading & Downloading
Upload the translation resources and download the translated
results by commands of Transifex Client.
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
tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start
tx push -s -r openstack-manuals-i18n.api-quick-start
www.openstack.org 17
18. Translation Process : Change Management
Synchronize the local translation resources with the resources in
the Transifex server by Transifex Client commands.
Command “tx push” will automatically check the differences and
merge the local copy and remote copy.
New strings will be added.
Modified strings will be considered new ones and added as well.
Strings which do not exist in the new source file (including ones which
have been modified) will be removed from the database.
The removed translations are kept in the Translation Memory of your
project.
./tools/generatedocbook -l zh_CN -b openstack-manuals-i18n.api-quick-
start
tx push -s -r openstack-manuals-i18n.api-quick-start
tx pull -r openstack-manuals-i18n.api-quick-start
www.openstack.org 18
19. Statics
5 languages translation started
Chinese – 11%, Spanish – 5%, Czech – 3%, Korean, French
15+ translators contributed.
Chinese translations
“OpenStack API Quick Start” 100% finished
“Network Administration Guide” 59% finished
“OpenStack Install and Deploy Manual” 44% finished
www.openstack.org 19
20. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 20
21. Sample : Chinese Document Generation
Step 1: Check out the sources from Git repository
git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git
Step 2: Check out the latest translation from Transifex
tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start
www.openstack.org 21
22. Sample : Chinese Document Generation
Step 3: Merge the translation segments back to DocBook
./tools/generatedocbook -l zh_CN -b api-quick-start
Step 4: Generate PDF and HTML document
mvn generate-sources
www.openstack.org
23. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 23
24. Plans for next steps
Integrate the process into Continuous Integration system.
Slicing & uploading
Downloading
Merging & publishing to website automatically
Updating
Resolve the issue: lack of translation context after slicing into
statements.
Using a website to show the up-to-date translated documents, to facilitate
the translators to check their translation results at any time.
Any kinds of contributions to translation process is warmly welcomed !
www.openstack.org
25. Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 25
26. How can I get on the openstack-core-docs team?
Do lots of reviews at http://review.openstack.org for the openstack-
manuals project.
Triage bugs and log doc bugs at
http://bugs.launchpad.net/openstack-manuals.
We’ll discuss on the openstack-docs-core mailing list and then invite
you.
www.openstack.org 26
27. How should I find doc work that needs to be
done on a particular project?
Refer to http://bugs.launchpad.net/openstack-manuals and look for
Wishlist for tasks, or any doc bug can be picked up as a work item.
We also track few blueprints which may need someone to work on,
though doc bugs are probably the best first place to look
www.openstack.org 27
28. Who should do reviews of my document
changes?
Anne Gentle, the doc coordinator, or anyone on the openstack-doc-
core team can help you identify reviewers, or you can also check
the doc bug and ask the reporter to review the changes by adding
their name to the reviewers list.
www.openstack.org 28
29. How to contribute the translations ?
If you want to contribute the translations, you need to register an
account at Transifex, and then go to openstack-manuals translation
page.
After that, select the languages you prefer, all of the language
resources will be listed. Then select the resources you want to work
on and click it. Click “Translate Now” in the pop-up dialog.
www.openstack.org 29
30. How to get the latest translation documents ?
Check out the latest resources from Git repository at first, and then
check out the latest translation from Transifex. After that, merge
the translation segment back to DocBook by running the Python
script and generate PDF and HTML document by running Maven
build.
Refer to “Sample: Chinese Document Generation”
www.openstack.org 30
31. Conclusion
Managing document as code is key feature of OpenStack
documentation.
The translation is just started. I will need the support and
participation from all of you.
Your participation is warmly welcomed.
For any problems about documentation, please contact with Anne
Gentle.
For any problems about translation, please contact with Ying Chun
Guo.
www.openstack.org 31
32. Reference
Documentation page
http://docs.openstack.org
Blueprints of documents
https://blueprints.launchpad.net/ openstack-manuals
Bugs of documents
http://bugs.launchpad.net/openstack-manuals
Main page for openstack-manuals translation in Transifex
https://www.transifex.net/projects/p/openstack-manuals-i18n/
OpenStack Document Translation Guide
https://gist.github.com/3037139
Address of Chinese Openstack manuals (as temporary)
http://1.openstackcn.sinaapp.com/?page_id=8
www.openstack.org