i18n - 2. 文档文件

本章的目的是对 Fink 的文档文件进行介绍，如何去访问它们，如何把你的修改通知 Fink 网站以及如何激活你的修改。

2.1 需求

要作为翻译团队的一员，开始对文档的翻译，你需要：

一个 CVS 客户端软件。用于从 Fink 网站下载网页的 xml 文件树。
一个 UTF-8 兼容的纯文本编辑器──专门的 XML 编辑器会更好，因为 Fink 网站的许多文件都是从 XML 文件生成的。
Fink 网页 xml 文件树的签出版本，如下面指南的介绍。
关译 Fink 的实践只是会是有益的。

附注：“团队成员”定义为负责翻译但不对最终上载文件到 Fink 站点负责的人。

团队领导必需符合上述要求，同时要：

有一个 SourceForge 帐号(免费注册)
对 Fink 文档树的修改权限。要获取这个权限，发一份邮件到 fink-18n 邮件列表，提供你的 SourceForge 用户名。 i18n 核心团队的一位成员会为你安排对文档部分 CVS 提交修改的权限事宜。

附注：“团队领导”在这里定义为负责实际上传修改过的文件到 Fink 网站，并激活有关修改的一个团队成员。

2.2 环境设置

你也许会希望事先设置好一些环境。下面的讨论假设你在使用 Mac OS X 或其它类 Unix 系统的内置命令行工具。

仅对团队领导：修改你的登录文件添加一个 CVS_RSH 环境变量。
1. 如果你使用的是 bash 或 zsh 添加下面一行：
```
export CVS_RSH=ssh
```
  到你的 .profile 文件中。
2. 如果你正在使用 tcsh，添加下面一行：
```
setenv CVS_RSH ssh
```
  到你的 .cshrc 文件中。
  这会告诉 cvs 程序使用 ssh 来下载文件。这个步骤是必需的。
对所有成员：在你的主目录中创建一个称为 .cvsrc 的文件，里面包括下面一行：
```
cvs -z3
```
这样，CVS 会默认使用第三级的压缩（这是个好东西！）。

这样做完以后，你需要重新开启一个新的终端窗口以使得你的 CVS_RSH 环境变量生效。

2.3 获取需要翻译的文件。

现在，你需要签出网站的 xml 分支：

打开终端窗口
创建一个你打算保存 Fink 网页文件树 XML 分支的目录，比如：
```
mkdir -p ~/Documents/Fink-i18n
```
进入这个目录：
```
cd ~/Documents/Fink-i18n
```
对于非团队领导的成员（或仍在等待修改许可的团队领导）： 以匿名方式登录 fink.cvs.sourceforge.net：
1. ```
cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink login
```
2. 按回车键（匿名方式不需要密码）
3. 签出 xml 模块：
```
cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
对团队领导：用你的用户帐号来签出：
1. 你不需要上面的登录步骤，而直接：
```
cvs -d:ext:yourusername@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
  其中 yourusername 是你的 SourceForge 用户名。
2. 这时，在提示输入密码的时候，你需要输入你的 SourceForge 用户密码。你也许会得到一个服务器的 DSA 密钥不能识别的警告信息，回答 yes 就可以了。

2.4 文件格式

作为一个翻译者，你需要处理两种格式的文件：

静态文件（仅PHP）
这些文档的结构（比如文本项的数目）不会每天改变。这种文档只使用 PHP 文件，你翻译它就可以了。
动态文件（由 XML 产生的 PHP 和 HTML）
这些文档（比如，FAQ 部分）会经常更新和调整结构，所以它需要一种可以动态重新组织的机制。这类文档使用 XML 文件作为产生 PHP 和 HTML 文件的基础，我们可以通过一个脚本从它生成需要的文件。作为翻译者，你的职责是翻译 XML 文件。

In addition, you will have to translate or modify a few other files, such as Makefile, nav.xx.inc, constants.xx.inc. Without them, the pages either will not appear on the web site or will not appear correctly.

All files are utf-8 encoded, consequently you should not change the encoding unless it is wrong (i.e. not utf-8), or use any html entities but those already in the English files.

2.5 更新到最新修订版

由于其它翻译者可能会在你签出文件以后，又对一些文件进行了修改（不用担心这一点，我们的 CVS 程序能够很好地处理它）。所以经常更新的版本到最新的修订版是一个好主意。

对于非团队领导的成员：

进入包含你签出的文件的目录，例如：
```
cd ~/Documents/Fink-i18n/xml
```
按照 2.3 中关于登录的步骤说明，登录到 CVS。

进行更新，例如：

cvs -d:pserver:anonymous@fink.cvs.sourceforge.net:/cvsroot/fink update -dP

对于团队领导：

进入包含你签出的文件的目录，例如：
```
cd ~/Documents/Fink-i18n/xml
```
进行更新，例如：
```
cvs update -dP
```
在提示的时候，输入你的 SourceForge 密码。

当你更新的时候，你会发现显示的信息中，有些文件前面又一个字母。查阅《附录》或 CVS 的帮助页获取更多的信息。

2.6 初始翻译

要翻译的文件，按照优先次序是：

标题（英语版本文件）

常数文件（xml/web/constants.*.inc）（参考下面）
静态 PHP 文件（例如：xml/web/*.en.php）
FAQ（xml/faq/faq.en.xml）
用户指南（xml/users-guide/uguide.en.xml）
运行 X11 （xml/x11/x11.en.xml）
文档目录（xml/doc/doc.en.xml，但由于尚余的 xslt 问题，它的 PHP 文件还不能用运行 make 的方法生成）
User's Guide (xml/users-guide/uguide.en.xml)
Advanced (xml/advanced/advanced.en.xml)
Running X11 (xml/x11/x11.en.xml)
CVS Access (xml/cvsaccess/cvs.en.xml)
Net Etiquette (xml/netiquette/netiquette.en.xml)
Internationalization (xml/multilingual/multilingual.en.xml)
ReadMe (xml/fink-readme/readme.en.xml)
Security (xml/security/security.en.xml)
Packaging Tutorial (xml/quick-start-pkg/quick-start-pkg.en.xml)
打包（xml/packaging/packaging.en.xml）
移植（xml/porting/porting.en.xml）
新闻（xml/news/news.en.xml）

constants.*.inc 文件是用于被 PHP 文件引用的固定编码的常数。它们主要是一些菜单项的内容，位于页面的上方或左方。你应该从脚本中分离它们，并创建一个你的语言的 constant.xx.inc 文件。你可以在终端窗口输入类似下面的命令：

cp constants.de.inc constants.xx.inc

这个 xx 是你的语言代码（例如：zh 是简体中文）。然后，你需要把 define 语句中的单引号内的内容翻译到你的语言。如果你不懂德语的化，下面是那个文件的英语版本：

/* The Sections. Used in Menu Navigation Bar */ define (FINK_SECTION_HOME, 'Home'); 
define (FINK_SECTION_DOWNLOAD, 'Download');
define (FINK_SECTION_PACKAGE, 'Packages'); 
define (FINK_SECTION_HELP, 'Help'); 
define (FINK_SECTION_FAQ, 'F.A.Q.'); 
define (FINK_SECTION_DOCUMENTATION, 'Documentation'); 
define (FINK_SECTION_MAILING_LISTS, 'Mailing Lists'); 

/* The Home Subsections. Used in Menu Navigation Bar */ 
define (FINK_SECTION_HOME_INDEX, 'Index'); 
define (FINK_SECTION_HOME_NEWS, 'News'); 
define (FINK_SECTION_HOME_ABOUT, 'About'); 
define (FINK_SECTION_HOME_CONTRIBUTORS, 'Contributors'); 
define (FINK_SECTION_HOME_LINKS, 'Links'); 

/* The word 'Sections'. Used in Menu Navigation Bar */ 
define (FINK_SECTIONS, 'Sections'); 

/* Contents as Table of Contents. Used in FAQ/Documentation Sections */ 
define (FINK_CONTENTS, 'Contents');

/* Printer */
define (FINK_PRINTER, 'Printer');
define (FINK_PRINT_VERSION, 'Print Version');

/* Footer */
define (META_KEYWORDS, 'Mac OS X, Fink, Debian, Macintosh, Apple, UNIX, Open Source,
             download, free software, port, development, package management');
define (META_DESCRIPTION, 'The Fink project wants to bring the full world of Unix Open
             Source software to Darwin and Mac OS X. We modify Unix software so that it 
             compiles and runs on Mac OS X and make it available for download as a coherent
             distribution.');
define (HEADER_HOSTED_BY, 'Hosted by {img}');
define (FOOTER_AVAILABLE_LANGUAGES, 'Available Languages');
define (FOOTER_GENERATED_DYNAMICALLY, 'Generated dynamically from');
define (FOOTER_DATABASE_LAST_UPDATED, 'Last updated: %x %X');
define (FOOTER_LAST_CHANGED, 'Last changed by {author} on %a, %d %b %Y,  %R %Z');

注意：Footer 部分的第一行由于显示的原因被分割成两行，在实际的文件不要这样分割。

在你翻译的时候，你通常会按照下面的步骤（假设你正在翻译《运行 X11》这份文档到简体中文）：

拷贝 xml 文件
```
cp x11.en.xml x11.zh.xml
```
编辑文件里面的这行来声明它是简体中文，以及它的字符编码是 UTF-8
```
<?xml version='1.0' encoding='utf-8' ?> ...
<document filename="index" lang="zh" > ...
```
Very important notice: Check that the cvsid line near the beginning of the file is not splitted.
保存为 UTF-8。注意字符编码格式必需为 utf-8，除了真正的文本内容以外，不要去修改任何其它内容（也就是那些尖括号里面的内容）。
翻译完成以后，或者你希望测试一下的话，编辑 Makefile 来包括你的语言：
```
LANGUAGES_AVAILABLE = en ja zh
```
然后在这个目录里面运行 make 命令。这应该会生成中文的 PHP 文件（可能还有一些其它文件），同时还有英语和其它已经在 Makefile 中添加了的语言版本。

注意：如果你发现英文文件的一些错误，不要修改它，而应该报告到 fink-i18n 邮件列表，这样英语主版本会得到更新。

2.7 检查你的工作

在你的工作被上传到 Fink 网站之前，你应该检查文档看起来是否正常。

简单的办法： 在你的浏览器里面打开 HTML 和 PHP 文件。不过，这样看的 PHP 文件和你在网站看到不完全相同。
最好的办法： 你可以使用你的内置 web 服务器，使得你看到这个文档应该在 Fink 网站尚的显示效果。假设你使用内置的服务器：
1. 编辑 /etc/httpd/httpd.conf 文件，比如通过：
```
sudo pico /etc/httpd/httpd.conf
```
2. 寻找这样一行：
```
#LoadModule php4_module libexec/httpd/libphp4.so
```
  然后删除它前面的 # 号。
3. 继续寻找这样一行：
```
#AddModule mod_php4.c
```
  删除它前面的 # 号
4. 如果你使用的 Apache 的版本比 Panther 内置的版本旧的话，你还需要寻找这样的一行：
```
AddType application/x-httpd-php.php
```
  并在前面放一个 # 号。
5. 存盘退出。
6. 在系统预置里面起动“个人网页共享”──如果它已经运行，那么关闭它然后再重新起动。
7. 使得所有的东西都可以被看得到的最简单的办法是把你签出的 xml 文件树移到你主目录下的 Sites 文件夹。然后你可以通过下面的 URL 打开你的网页：
```
http://127.0.0.1/~USERNAME/xml/web/index.php
```
  这里 USERNAME 应该替换为你的用户名。

2.8 当你获得提交修改的权限（团队领导）

当你被授予提交修改的权限以后，你应该

为你的 SourceForge 帐号设置一个 SSH 密钥。
1. 按照 SourceForge 上《指南》的介绍，在你的机器上设置好密钥。
2. 在终端窗口输入：
```
cat ~/.ssh/id_dsa.pub | pbcopy
```
  这会把文件的内容直接拷贝到你的剪贴版，而避免那些讨厌的换行符问题。注意在你完成下一步操作之前，不要再拷贝其它东西到剪贴板。
3. 登录你的 SourceForge 帐号。
4. 选择 “Account Options”
5. 找到 “Host Access Information” 设置的地方，点击 “Edit SSH Keys for Shell/CVS”
6. 点击输入框，按 Cmd-A，Cmd-V
7. 点击按钮。
用你的用户名签出 xml 代码树。
1. 如果以前已经签出了整个 xml 代码树，那么你应该先重命令你本地的文件。你可以用 Finder 来做。
2. 在终端窗口进入那个目录：
```
cd ~/Documents/Fink-i18n
```
3. 签出 xml 代码树：
```
cvs -d:ext:yourusername@fink.cvs.sourceforge.net:/cvsroot/fink co xml
```
  这里 yourusername 当然是你的 SourceForge 用户名。在提示的时候输入你的密码。
4. 把你正在翻译的文件从旧的文件树拷贝回新的代码树。你可以使用 Finder，要注意它们应该被拷贝到同样的目录位置。

2.9 提交修改（团队领导）

现在你需要把你的修改发送到主服务器。要这样做，你需要有提交修改的权限。你还需要确保你使用的未稳定树里面的最新的 XSLT 版本，写本文档时用的是 Fink 的 libxslt-1.1.4-1。

对于静态和动态的文档，根据它们的性质不同，提交方法也有不同：

静态：（仅 PHP 文件）。要提交对这些文件的修改，可以这样：
1. 打开一个终端程序。
2. 进入你包含你打算提交的文件所在的目录：
```
cd ~/Documents/Fink-i18n/xml/web
```
  上面假设你把你的 xml 代码树建立在你主目录下的 Documents/Fink-i18n/ 文件夹下，并且你打算提交 xml/web 目录里面的 PHP 文件。
3. 如果这是一个你新创建的文件，那么你需要先把它添加到文件清单中，例如：
```
cvs add download.ru.php
```
  在提示的时候输入你的 SourceForge 密码。你也许会获得一个未知的服务器的 DSA 密钥的警告。输入 yes 就好了。
  如果是一个现有的文件，你可以跳过这一步而进入下一步。
4. 提交文件，例如，对于上面的例子：
```
cvs ci -m "message" download.ru.php
```
  这里 message 应该能够描述你大概做了什么修改。在提示的时候输入你的 SourceForge 密码。
  附注：你可以一次提交多个文件。
动态：（XML 和 PHP）在修改了 XML 文件以后，按照下面那样做：
1. 打开一个终端程序
2. 进入包含你要添加和修改的文件的目录，例如：
```
cd ~/Documents/Fink-i18n/xml/faq
```
  如果你是在翻译 FAQ 部分的话。
3. 现在运行
```
make check
```
  验证文件的格式是正确的。
4. 如果这个 XML 文件是你新创建的，那么你需要把它添加到文件清单中，例如：
```
cvs add faq.ru.xml
```
  在提示的时候输入你的 SourceForge 密码。
  如果是一个现有的文件，你可以跳过这一步而进入下一步。
5. 提交文件。例如：
```
cvs ci -m "message" faq.ru.xml Makefile
```
  message 是一个关于你的操作的描述性信息。在提示的时候输入你的 SourceForge 密码。我们这里假设你还修改过 Makefile 文件（例如，你在里面添加了你的语言），如果你没有对它修改过，你只需要提交 xml 文件就可以了。
6. 现在运行
```
make && make install
```
7. 进入网站 XML 代码树的目录中，例如：
```
cd ~/Documents/Fink-i18n/xml
```
  上面假设你把你的 xml 代码树建立在你主目录下的 Documents/Fink-i18n/ 文件夹下。
8. 如果 XML 是一个新文件，你需要把它先添加到 CVS 中。例如，如果你在翻译 FAQ 部分，那么，你需要运行：
```
cvs add web/faq/index.en.php web/faq/general.ru.php \
web/faq/relations.ru.php web/faq/usage-fink.ru.php \
web/comp-general.ru.php web/faq/comp-packages.ru.php \
web/faq/usage-general.ru.php web/faq/usage-packages.ru.php \
web/faq/upgrade-fink.ru.php web/faq/mirrors.ru.php \
web/faq/faq.ru.html web/faq/header.ru.inc \
scripts/installer/dmg/faq.ru.html
```
  对于其它文档，文件当然会不同──你应该添加 make install 命令所新产生的和你语言有关的文件。
9. 不要忘记添加和提交你所创建的所有文件（它们可能还包括 constants.xx.inc，header.xx.inc，nav.xx.inc，等等）
  如果这些文件原来已经有，你可以跳过这一步。
10. 提交整个文件树：
```
cvs ci -m "message"
```
  这里 message 也是一个描述性的日志信息（你可能会使用你提交 XML 文件相同的信息）。在提示的时候输入你的 SourceForge 密码。
  
  要分两次进行 commit 的原因是只有这样才能在生成的网页上正确显示修改时间和最后修改者的名字。

2.10 更新我们的网站

想现在我们的网站上就看到你的成果吗？你只需要这样做：

打开一个终端程序
用 ssh 登录网页服务器：
```
ssh username@shell.sourceforge.net
```
你会需要输入你的 SourceForge 密码。
进入包含我们网页文件的目录：
```
cd /home/groups/f/fi/fink/htdocs
```
根据 CVS 的内容更新网页：
```
./update.sh
```
重要提示：当你这样做的时候，你会更新web/xml下的所有内容到网站上。
从服务器上注销：
```
exit
```
检查你的成果：
```
open /
```

Next: 3. 更新文档的流程