2. 议程
Agenda
OpenStack 文档现状
Status of OpenStack Document
翻译管理及流程
Translation Management & Process
翻译流程示例
Samples of Translation Process
常见问题解答
Questions with Answers
www.openstack.org 2
3. 议程
Agenda
OpenStack 文档现状
Status of OpenStack Document
翻译管理及流程
Translation Management & Process
翻译流程示例
Samples of Translation Process
常见问题解答
Questions with Answers
www.openstack.org 3
4. 文档页面
Web Page for Documentation
http://docs.openstack.org
www.openstack.org
5. 社区文档的挑战
Challenges of Community Documentation
代码量巨大 增长很快
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
现有的蓝图可以在 https://blueprints.launchpad.net/openstack-manuals
上找到
Current blueprints found at https://blueprints.launchpad.net/
openstack-manuals
www.openstack.org 6
7. 文档流程：开发
Document Process ： Development
管理员指南和 API 指南存储于 Github 代码库
Github repositories store admin guides and API guides
单元测试集成在 Jenkins 中
Unit tests with Jenkins
补丁包的审核通过 Gerrit 进行
Patch review with Gerrit
www.openstack.org 7
9. 文档流程：发布
Document Process ： Publishing
通过 Jenkins 上的任务进行自动发布
Automatically publish with Jenkins
www.openstack.org 9
10. 文档小组成员
Doc Team Composition
所有的 OpenStack 社区成员
All OpenStack community members
OpenStack 文档小组的成员只占其中的百分之一
One percenter = OpenStack-doc-core
小组成员主要来自下列公司：
Badge Wearers
AT&T
IBM
Nebula
Nicira
Nimbis Services
Nuage
Rackspace
RedHat
www.openstack.org 10
11. 统计
Statics
api.openstack.org 中有 20 多个计算扩展 API 的文档描述。
20+ Compute Extensions documented at api.openstack.org
66% 的网站访问者会选择继续浏览而不是离开
66% Site visitors stay instead of leaving
一个月进行 100 的文档补丁包的审查
100 Doc patches and reviews a month
记录了 726 个配置选项。其中， 467 个为 nova 配置选项， 259 个为 swift
配置选项
726 Configuration options: 467 for nova.conf, 259 for swift conf files
docs.openstack.org 一周的唯一访问量为 10,000
10,000 Unique visitors a week at docs.openstack.org
www.openstack.org 11
12. 议程
Agenda
OpenStack 文档现状
Status of OpenStack Document
翻译管理及流程
Translation Management & Process
翻译流程示例
Samples of Translation Process
常见问题解答
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
通过一个 Python 脚本，将 DocBook 切分为字符串片断，整理为一个 PO 模板。
Slice DocBook into string segment with a Python script, and generate a PO
template 。
./tools/generatepot openstack-compute-admin
www.openstack.org 14
16. 文档翻译流程：合并
Translation Process ： Merging
通过一个 Python 脚本，将翻译后的字符串合并到 DocBook 中。
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
借助 Transifex 的客户端命令，完成翻译资源和翻译结果的上传下载。
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 push -s -r openstack-manuals-i18n.api-quick-start
tx pull -f -l zh_CN -r openstack-manuals-i18n.api-quick-start
www.openstack.org 17
18. 文档翻译流程：变更管理
Translation Process ： Change Management
借助 Transifex 客户端命令，将本地翻译资源与服务器上的资源进行同步。
Synchronize the local translation resources with the resources in the Transifex
server by Transifex Client commands.
当输入“ tx push” 命令将本地资源更新到服务器端时，会自动地检查本地资源与服务器资源的
不同，并且进行合并。
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
OpenStack 手册的 7 本书已经上传到 Transifex 上，包含 5550 个待翻译项。
7 books of OpenStack Manuals have been uploaded to Transifex, including 5550
items for translation.
6 个翻译小组在 Transifex 上已建立，负责如下 6 种语言的翻译：
6 translation teams created in Transifex for 6 languages translation:
中文，西班牙语，法语，日语，韩语，土耳其语
Chinese, Spanish, French, Japanese, Korean, Turkish (Turkey)
3 种语言的翻译工作已经启动
3 languages translation started
中文 – 4% ，西班牙 – 4% ，法语 - 1%
Chinese – 4 %, Spanish – 4 %, French – 1 %
已有 9 人加入中文翻译小组
9 translators joined Chinese translation team
一本中文手册完成翻译
1 manual document finished Chinese translation
OpenStack API 快速入门
OpenStack API Quick Start
www.openstack.org 19
20. 议程
Agenda
OpenStack 文档现状
Status of OpenStack Document
翻译管理及流程
Translation Management & Process
翻译流程示例
Samples of Translation Process
常见问题解答
Questions with Answers
www.openstack.org 20
21. 示例：中文文档生成
Sample ： Chinese Document Generation
步骤一：从 Git 代码仓库中检出所有的 OpenStack 手册的源码
Step 1: Check out the sources from Git repository
git clone https://github.com/daisy-ycguo/openstack-manuals-i18n.git
步骤二：从 Transifex 中检出最新的翻译结果
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
步骤三：将翻译结果合并到 DocBook 中，生成中文的 DocBook
Step 3: Merge the translation segment back to DocBook
./tools/generatedocbook -l zh_CN -b api-quick-start
步骤四：根据中文 DocBook ，生成中文 PDF 和 HTML 文档
Step 4: Generate PDF and HTML document
mvn generate-sources
www.openstack.org
23. 议程
Agenda
OpenStack 文档现状
Status of OpenStack Document
翻译管理及流程
Translation Management & Process
翻译流程示例
Samples of Translation Process
常见问题解答
Questions with Answers
www.openstack.org 23
24. 如何加入 openstack-core-docs 组
How can I get on the openstack-core-docs team?
大量审阅 http://review.openstack.org 上的 openstack-manuals 项目
Do lots of reviews at http://review.openstack.org for the openstack-
manuals project.
参与 Bug 的分类和修正工作 http://bugs.launchpad.net/openstack-
manuals
Triage bugs and log doc bugs at
http://bugs.launchpad.net/openstack-manuals.
我们会在邮件列表 openstack-docs-core 通过讨论，邀请你加入 openstack-
core-docs 组。
We’ll discuss on the openstack-docs-core mailing list and then
invite you.
www.openstack.org 24
25. 如何找到某个项目需要做的文档工作列表？
How should I find doc work that needs to be
done on a particular project?
您可以到 http://bugs.launchpad.net/openstack-manuals 寻找含有
wishlist 字样的任务，或者任何其它的 bug ，都可以作为工作项。
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.
Bug 是最值得一看的地方，但是我们也通过少量的蓝图来跟踪某个工作。
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 25
26. 谁会复审我对文档的修改？
Who should do reviews of my document
changes?
Anne Gentle ，文档协调人，又或者任意 openstack-doc-core 的成员都可
以帮助你来制定审查人。或者你可以把 bug 报告者的名字加到审查人列表中
去。
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 26
27. 如何加入翻译工作小组？
How to join the translation team ？
在 www.transifex.net 上注册一个账号，打开 openstack 手册翻译的页面，
选择你熟悉的语言，然后点击右上角的“ join team” 。
Register an account at www.transifex.com firstly, and then go to
openstack-manuals translation page. After that, select your favorite
language and click “join team” at the top right corner.
你的加入请求需要被该语言的协调人批准。
Your request will be approved by the language coordinator.
www.openstack.org 27
28. 如何获得最新的翻译文稿？
How to get the latest translation documents ？
从 Git 代码库中检出最新的手册代码，从 Transifex 中检出最新的翻译结果，
将翻译结果合并到文档中，生成新的 DocBook 。通过运行 Maven 命令，就
可以生成最新的翻译后的手册了。
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 28
29. 结束曲
Conclusion
象对待代码一样管理文档，是 OpenStack 社区文档成功的关键。
Managing document as code is key to the success of OpenStack
documentation.
OpenStack 翻译工作刚刚开始，还需要大家的大力支持和参与。
The translation is just started. I will need the support and participation
from all of you.
欢迎大家加入到 OpenStack 文档工作中来。
Your participation is warmly welcomed.
有任何关于文档的问题，都可以联系 Anne Gentle 。
For any problems about documentation, please contact with Anne Gentle.
有任何关于翻译的问题，都可以联系我。
For any problems about translation, please contact with me.
www.openstack.org 29
30. 参考资料
Reference
文档页面
Documentation page
http://docs.openstack.org
文档设计蓝图
Blueprints of documents
https://blueprints.launchpad.net/ openstack-manuals
文档 Bug 列表
Bugs of documents
http://bugs.launchpad.net/openstack-manuals
Transifex 上的文档翻译主页面
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
