翻译 DocBook 文档的方法

2. defguide 的翻译方法

2.1. 更新 po 文件

    msgmerge --width=80 --sort-by-file -o zh_new.po zh.po defguide.pot
    mv -f zh_new.po zh.po

2.2. 翻译 po 文件

使用 poedit 或 KBabel，甚至普通文本编辑器。

2.3. 查阅上下文

如果翻译时不能确定语义环境，那么请运行 ant pot，则对应的条目有其在 source/defguide.xml 中的位置，例如：

    #. (para)
    #: ../source/defguide.xml:8360
    msgid "Add new elements"
    msgstr "增加元素"

打开 source/defguide.xml，定位到 8360 行即可。

2.4. 格式化 po 文件

统一采用 80 列宽，按照文件位置排序的 gettext 翻译格式，请在提交之前先格式化 po 文件。

gettext 的 Windows 平台二进制包可以从 i18n-zh 下载。

    msgcat --width=80 --sort-by-file -o zh_new.po zh.po
    mv -f zh_new.po zh.po

2.5. 合并 po 文件

如果合作者有约定协作翻译的方法，请略过本节。

下面的例子是以他人的翻译(zh-other.po)为准合并。如果需要以自己的翻译(zh.po) 为准合并，交换下述命令中的 zh.po 和 zh-other.po 即可。

2.5.1. 使用 Subversion 的 po-merge.py

    subversion/tools/dev/po-merge.py zh.po < zh-other.po

2.5.2. 使用 translation tookit 的 pomerge

    pomerge -i zh-other.po -o zh-new.po -t zh.po

2.6. 检查 po 文件

    msgfmt --statistics -c zh.po

3. defguide 的构建方法

3.1. 安装软件包

在 Debian 系统中，安装方法如下：

% sudo apt-get install openjdk-6-jdk ant ant-optional libbsf-java bsh \
    libsaxon-java docbook-xml docbook-xsl python-libxml2 gettext

对于其它系统，请参考 Debian 系统的安装方法。

此外，还需要手工安装 docbook 5.0 和 RELAX NG Support(jing)，配置 ant 支持 BeanShell 脚本。如果要生成 pdf，还需要安装中文字体，以及 fop trunk 2008-09-25(r698670) 以上版本。

3.2. 配置构建环境

请根据 build.properties.tmpl 创建 build.properties：

docbook5.home ----- docbook 5.0 安装的根目录
docbook.xsl ------- docbook-xsl 安装的根目录(e.g. /usr/share/xml/docbook/stylesheet/nwalsh)
usr.share.java ---- 存放共享 jar 文件的目录(e.g. /usr/share/java)

3.3. 配置 xml catalog

在 Debian 系统中，直接复制 CatalogManager.properties.tmpl 为 CatalogManager.properties，放到 ${usr.share.java} 目录即可。对于其它系统，可能需要少许修改。

catalogs=/etc/xml/catalog
relative-catalogs=true
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1

3.4. 配置构建环境

然后就可以构建 html 或 pdf 输出格式的文档了：

Building 'The Definitive Guide' - html
    $ ant html

Building 'The Definitive Guide' - pdf
    $ ant pdf

请付出耐心，因为在 Intel Xeon 2.00GHz 的主机上，完全构建 html 需要近 100 分钟，完全构建 pdf 需要近 80 分钟。

祝你好运！