openstack document for apac v3

© 2009 IBM Corporation

OpenStack 文档及其翻译管理

OpenStack Documentation and Translation Management

2012 OpenStack APAC Conference11 Aug 2012

郭迎春OpenStack 文档组

[email protected]

Anne GentleOpenStack 文档组

[email protected]

www.openstack.org 2

议程Agenda

OpenStack 文档现状Status of OpenStack Document

翻译管理及流程Translation Management & Process

翻译流程示例Samples of Translation Process

常见问题解答Questions with Answers

www.openstack.org 3

议程Agenda





www.openstack.org

文档页面Web Page for Documentation

http://docs.openstack.org

www.openstack.org 5

社区文档的挑战Challenges of Community Documentation

代码量巨大

Large amount of code

经常变化

Change frequently

增长很快

Grow quickly

松散管理

Loose coupling

如同管理代码那样管理社区文档！Manage document as code !

www.openstack.org 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 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 8

文档流程： Bug 跟踪

Document Process ： Bug tracking

通过 Launchpad 管理 Bug Manage bugs through Launchpad

Bug logging Bug 登记

Bug triaging Bug 分类

Bug assigning Bug 指派

www.openstack.org 9

文档流程：发布Document Process ： Publishing

通过 Jenkins 上的任务进行自动发布 Automatically publish with Jenkins

www.openstack.org 10

文档小组成员Doc Team Composition

所有的 OpenStack 社区成员 All OpenStack community members

OpenStack 文档小组的成员只占其中的百分之一 One percenter = OpenStack-doc-core

小组成员主要来自下列公司： Badge Wearers

AT&T IBMNebulaNiciraNimbis ServicesNuageRackspaceRedHat


统计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


议程Agenda






文档翻译的挑战Challenges of Document Translation

代码量巨大

Large amount of code

经常变化

Change frequently

增长很快

Grow quickly

松散管理

Loose coupling

如同管理代码中字符串翻译那样管理社区文档翻译！Manage document translation as code string translation!


文档翻译流程：切分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


文档翻译流程：翻译Translation Process ： Translating

借助 Transifex 进行翻译管理翻译项目和资源翻译内存术语

Manage translation by TransifexTranslation project & resourcesTranslation memoryGlossary


文档翻译流程：合并Translation Process ： Merging

通过一个 Python 脚本，将翻译后的字符串合并到 DocBook 中。 Merge the translated string into Docbook with a python script.

./tools/generatedocbook -l zh_CN -b openstack-compute-admin


文档翻译流程：上传与下载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


文档翻译流程：变更管理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-starttx push -s -r openstack-manuals-i18n.api-quick-starttx pull -r openstack-manuals-i18n.api-quick-start


统计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


议程Agenda






示例：中文文档生成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

示例：中文文档生成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


议程Agenda






如何加入 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.


如何找到某个项目需要做的文档工作列表？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


谁会复审我对文档的修改？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.


如何加入翻译工作小组？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.


如何获得最新的翻译文稿？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”


结束曲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

参考资料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

http://bugs.launchpad.net/openstack-manuals

https://www.transifex.net/projects/p/openstack-manuals-i18n/

https://gist.github.com/3037139

openstack document for apac v3

Technology