Embed Size (px)
DESCRIPTION
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.
Citation preview
© 2009 IBM Corporation
OpenStack Documentation and Translation Management
The OpenStack SummitSan Diago 2012
Ying Chun Guo (Daisy)OpenStack Doc [email protected]
Anne GentleOpenStack Doc [email protected]
2www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
3www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org
文档页面Web Page for Documentation
http://docs.openstack.org
5www.openstack.org
Challenges of Community Document
Large amount of code
Change frequently
Grow quickly
Loose coupling
Manage document as code !
6www.openstack.org
Document Process: Design
Blueprints and discussion at Design Summit
Blueprints
Current blueprints found at https://blueprints.launchpad.net/openstack-manuals
7www.openstack.org
Document Process：Development
Github repositories store admin guides and API guides
Unit tests with Jenkins
Patch review with Gerrit
8www.openstack.org
Document Process：Bug tracking
Manage bugs through LanuchpadBug loggingBug triagingBug assigning
9www.openstack.org
Document Process： Publishing
Automatically publish with Jenkins
10www.openstack.org
Doc Team Composition
All OpenStack community members
One percenters = OpenStack-doc-core
Badge WearersAT&T IBMNebulaNiciraNimbis ServicesNuageRackspaceRedHat
11www.openstack.org
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
12www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
13www.openstack.org
Challenges of Document Translation
Large amount of code
Change frequently
Grow quickly
Loose coupling
Manage document translation as code string translation!
14www.openstack.org
Translation Process： Slicing
Slice DocBook into string segment with a Python script, and generate a PO template
./tools/generatepot openstack-compute-admin
15www.openstack.org
Translation Process： Translating
Manage translation by TransifexTranslation project & resourcesTranslation memoryGlossary
16www.openstack.org
Translation Process：Merging
Merge the translated string into Docbook with a python script.
./tools/generatedocbook -l zh_CN -b openstack-compute-admin
17www.openstack.org
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
18www.openstack.org
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
19www.openstack.org
Statics
5 languages translation startedChinese – 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
20www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org 21
Sample： Chinese Document Generation
Step 1: Check out the sources from Git repositorygit clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git
Step 2: Check out the latest translation from Transifextx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start
www.openstack.org
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 documentmvn generate-sources
23www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Plans for next steps
Questions with Answers
www.openstack.org
Plans for next steps
Integrate the process into Continuous Integration system.Slicing & uploadingDownloadingMerging & publishing to website automaticallyUpdating
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 !
25www.openstack.org
Agenda
Status of OpenStack Document
Translation Management & Process
Samples of Translation Process
Questions with Answers
Plans for next steps
26www.openstack.org
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.
27www.openstack.org
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
28www.openstack.org
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.
29www.openstack.org
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.
30www.openstack.org
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”
31www.openstack.org
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
ReferenceDocumentation page
http://docs.openstack.org
Blueprints of documentshttps://blueprints.launchpad.net/ openstack-manuals
Bugs of documentshttp://bugs.launchpad.net/openstack-manuals
Main page for openstack-manuals translation in Transifexhttps://www.transifex.net/projects/p/openstack-manuals-i18n/
OpenStack Document Translation Guidehttps://gist.github.com/3037139
Address of Chinese Openstack manuals (as temporary)http://1.openstackcn.sinaapp.com/?page_id=8
