readme.first

/* $Id$ */

=========================
  2020-09-02 by Avenger
=========================

以下翻译指南大部分内容已经过时，准备重启中文手册翻译计划，有兴趣的同学可
以先参见以下链接：

PHP 中文手册翻译指南：https://github.com/php/doc-zh
官方指南：http://doc.php.net/tutorial/
官方翻译指南：http://doc.php.net/tutorial/translating.php

最新动态可以关注邮件列表，参考下面的「订阅邮件列表的附加说明」一节，WEB
版本可以通过下面链接访问：

https://news-web.php.net/group.php?group=php.doc.zh

目前，最简单的参与翻译方式，使用官网提供的编辑器在线翻译：

https://edit.php.net

=========================
  2013-03-10 by Dallas
=========================

  请大家在此留下有助于翻译工作的任何信息并添加上日期标识。本文件的上次
  更新时间是 2009-09-23，其中有些内容可能已经过时。

======================
  在加入翻译小组之前
======================

　　PHP 文档的翻译工作完全是一项志愿行动，你不会从中得到任何利益。而且
要建立起一个适合进行翻译工作的环境也是相当繁琐的，例如申请 SVN 账号，
拥有 Unix/Linux 或者 Cygwin 的环境以及 SVN 工具，订阅相关的邮件列表，
翻译完成后还要继续关注英文文档是否有了更新等等。

　　你能得到的是什么呢？是一种无私奉献并与世界各地的同好们一起工作的乐
趣，英文翻译水平的提高（希望这样），对 PHP 更加深入的了解以及在 PHP 文
档的中文页面中署上你的大名。

　　如果你不能满足下面的所有条件，那么你可能不适合加入 PHP 文档的翻译
工作：

1.  愿意进行无私奉献加入这个志愿行动；
2.  英文程度较好；有较好的汉语书面表达能力。
3.  对 PHP 本身有相当的了解；
4.  对 Unix/Linux 有相当了解，能够自行建立起 SVN 的工作环境；
5.  在参与翻译工作时（请注意这一点）愿意为此投入较多时间，并且能够迅速
    完成自己承担的文件的翻译工作。不要因为一时冲动加入了翻译工作之后，
    所经手的文件完成一部分之后却由于种种原因而不能继续下去。大家都不希
    望看到一个文件历时数个星期甚至数月都未能完成翻译工作；
6.  以后能够定期访问并且尽量更新自己所维护的文件。

　　假如你能够做到以上这几点，那么欢迎你加入 PHP 中文文档翻译小组！

　　实在难以建立 SVN 工作环境或者申请不到 SVN 账号的朋友如果愿意参与，
也可以采用折衷的方法，就是将翻译好的文件发给有 SVN 账号的成员，让他们
帮你提交。

========================
  翻译中需要注意的问题
========================

1.  文件是 UNIX 的文件格式而不是 DOS 的，也就是文件中的换行标记只有换
    行符（\n），而没有回车符（\r）。并且在文件中不要使用 <TAB>（制表符
    \t）而要使用空格；
2.  请注意翻译中的标点问题，使用中文标点符号；
3.  中英文字词之间使用空格分开，与中文标点之间就不要有空格了；
4.  不要翻译 TRUE，FALSE，Boolean 之类的词。翻译中请注意！
5.  请翻译的时候注意使用书面用语，翻译完成后检查确认没有错别字和其它错
    误后再提交！
6.  请参加翻译的人员在 translation.xml 中添加自己的资料，并在确定自己
    翻译某个文件后立即更新自己的工作进展情况，而不是在翻译完成后，以免
    别人的重复劳动。这是必须做的工作，方便控制翻译进度；
7.  请在翻译前认真阅读 PHP Documentation HOWTO，尤其是该文档的第 9 章
    Information for Translators。其简体中文版已经翻译完成，下载方式在
    本文“如何在 Windows 环境下利用 CVS 账号进行翻译工作”一节有说明。
8.  请参加翻译的人员加入 doc-zh@lists.php.net 邮件列表.具体方法是向
    doc-zh-subscribe@lists.php.net 发一封空白电子邮件，然后回信确认。
    我们在这这个邮件列表里面讨论和协调翻译工作。该邮件列表的内容可以通
    过如下地址访问 http://news.php.net/group.php?group=php.doc.zh；
9.  请参加翻译的人员，一定要在提交翻译完成的 XML 文件前运行
    `php configure.php --with-lang=zh` 命令，检查文件是否有语法和拼写
    错误。

==========================
  标识自己的 ID 以及工作
==========================

　　请参照 translation.xml 中已有人员的样式添加自己的 ID。例如：

<person name="王远之" email="dallas@php.net" nick="dallas" vcs="yes" svn="yes" />

name  : 会显示在编译后的文档中的首页
email : 与你联系的电子邮件地址，请确保使用此邮件地址可以联络到你，不一
        定要是 @php.net 的。
nick  : 给自己起的昵称。请确保在文档头中的 Maintainer 与此保持一致。
svn   : 是否有 svn 的账号。
vcs   : revcheck.php 中用 vcs 这个词来检查

　　为便于跟踪翻译工作以及保持与英文文档一致，请用以下四行代替原来英文
文档的前两行。

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- $Author$ -->
<!-- EN-Revision: 324085 Maintainer: verdana Status: ready -->

有时也可以加入这样一行：

<!-- CREDITS: Gregory,dallas -->

$Revision   : 中文文档的版本号，自动更新，新文件总是从 1.1 开始
$Author     : 最后一次 checkin 的人员的 cvs 账号，自动更新
EN-Revision : 与当前中文文档相对应的英文文档的版本号，非常重要！方便后
              续文档更新检测。
Maintainer  : 此中文文档的维护者，一定要与 translation.xml 中的 nick
              相同，区分大小写！
Status      : 翻译完成后写 ready，翻译一部分的写 partial
CREDITS     : 如果你对别人维护的文档做了重大更新或者完成了其中相当大的
              一部分翻译工作，请在这里添上你的昵称，多个人用逗号隔开

==========================
  订阅邮件列表的附加说明
==========================

　　很多人可能出于各种考虑不希望有大量邮件进入自己的信箱。建议大家使用
Outlook Express 本身具有的新闻组功能。方法是在 OE 的工具菜单下选择账号
然后新增一个新闻组帐号，服务器名为  news.php.net。然后在其中订阅相应的
新闻组，这样所有的新闻组邮件就可以通过 OE 来在线观看而不用订阅邮件列表
了，这和订阅邮件列表功能完全相同而且更加直观。

　　必须订阅的新闻组是 php.doc 和 php.doc.zh。前者可以看到所有英文版文
件的更新而后者是中文文件的更新以及中文翻译小组交流的地方。

　　要在某个新闻组发言，需要进行身份认证，这是个一次性的工作。首次向某
个新闻组发帖子后会收到一封邮件，只要回复该邮件就可以通过认证，自己的发
言才会显示在新闻组中，并且发送给相应的邮件列表成员。

　　要注意的是回复认证时所使用的自己的邮件地址必须就是首次发言时所使用
的邮件地址。

   推荐使用 gmail 邮箱来订阅邮件列表，可以通过创建 filter 将邮件列表中的
   邮件贴上标签（tag，如 php-doc-zh）并归档保存，不直接显示在收件箱中，
   不会影响其它日常邮件的浏览。

==========================================================
How to translate via the new SVN system instead of the CVS
使用新的 SVN 版本控制系统代替 CVS 系统 -- Haohappy
==========================================================

PHP官方的版本控制系统已经完全转移到 SVN 平台，包括文档翻译。
作为译者，首先需要把你的 CVS 帐号同步到 SVN 上，然后才能翻译并提交文件。

1. 取得手册 XML
svn checkout http://svn.php.net/repository/phpdoc/zh/trunk

2. 激活 SVN 帐号的办法 （前提是有一个可用的CVS帐号）
首先需要验证你的 CVS 帐号可用，有三个办法（任选其一即可）：
登录 https://master.php.net/login.php 或 登录 wiki (http://wiki.php.net)
或 在 bugsweb 回复某个bug报告 (http://bugs.php.net/)
你的 CVS 帐号会在 15 分钟后同步到 SVN，然后你就可以用原来的用户名密码登录并提交文件。

==============================================
  有关在翻译后的中文文件中的空格与换行的说明
==============================================

　　在原始的英文 XML 文件中不存在此问题，因为英文单词之间本来就有一个
空格，而无论是 XML 文件还是编译后的 HTML 文件对待任何连续的空格，回车
以及制表符都当成一个空格看待。但是在中文书写习惯中，汉字之间以及与中文
标点符号之间都是没有空格的。因此英文文件中类似这样的段落：

   <para>
    This section applies to Windows 95/98/Me and
    Windows NT/2000/XP. Do not expect PHP to work on
    16 bit platforms such as Windows 3.1. Sometimes
    we refer to the supported Windows platforms as Win32.
   </para>

在编译后显示出来当然完全正常。可是如果翻译成这样：

   <para>
    本节内容适用于 Windows 95/98/Me 以及 Windows NT/2000/XP。
    PHP 不能在16位平台例如 Windows 3.1 下运行。有时我们把
    支持 PHP 的 Windows 平台称为 Win32。
   </para>

就会在 HTML 页面显示时在“XP。”和“PHP 不能”以及“我们把”和“支持”
之间出现一个不希望的空格，破坏了页面的美观。这种情况下当然可以将翻译的
结果全部放到同一行中来解决，例如：

   <para>
    本节内容适用于 Windows 95/98/Me 以及 Windows NT/2000/XP。PHP 不能在16位平台例如 Windows 3.1 下运行。有时我们把支持 PHP 的 Windows 平台称为 Win32。
   </para>

但这样给翻译时的阅读又带来了不便。可用的解决方法是在翻译后的文件中保留
下来的英文单词前后换行 － 既然中英文字词之间本来就是用空格隔开的并且一
个空格和多个空格也没什么区别。那么以上这一段在中文文件中可以写成这样：
（要注意，不要在中文标点符号前后换行！）

   <para>
    本节内容适用于 Windows 95/98/Me 以及
    Windows NT/2000/XP。PHP 不能在16位平台例如
    Windows 3.1 下运行。有时我们把支持
    PHP 的 Windows 平台称为 Win32。
   </para>

这样一来显示的时候就没问题了。如果翻译后结果是一大段纯中文的文本，那就
没办法了，只能老老实实放在同一行，即使很长很长。

总之原则是在保证显示出来的页面美观无误的情况下兼顾原始 XML 文件的可读性。

==========================
  我的工作环境 － Dallas
==========================

　　本人的工作环境如下：

操作系统：Windows XP Professional English Version
CVS 环境：用 VMWare Workstation 安装的 FreeBSD 5.0-RELEASE
编辑器  ：UltraEdit 9.10b

用 VMWare 安装的 FreeBSD 可以保证拥有一个原汁原味的 UNIX  系统，这比用
Cygwin 要好得多。可以同时使用 Linux 和 Windows  各自的特色和优点。只要
用 samba 将 phpdoc 目录共享出来就可以用 UltraEdit 直接对源文件进行操作
了。

UltraEdit 可以正确识别并转换 Unix 和 DOS  的文件格式，避免出错，并
且本身就具有了 XML  文件的语法高亮显示。还可以定义一些宏，将经常出现的
字词自动替换，省掉一些手工劳动。

VMWare Workstation 当前版本是 4.0.0，非常方便易用，不到 20M 的大小，
可以用它安装各个版本的 Linux 或者 FreeBSD。由于进行 PHP 文档翻译工作只
需要文本模式，因此安装后的大小可以在 500M 以下，而且所需要的内存可以设
定在 32M 就足够了，并不消耗很多系统资源。Virtual PC 的爱好者当然也可以
选择 Virtual PC。

==========================
  我的工作环境 － Gregory
==========================

    本人的工作环境如下：

    操作系统：Windows 2000 Server / Professional 简体中文版
    CVS 环境：Cygwin + WinCVS 1.3.8.1
    编辑器：Editplus 2.11c

    由于本人对 Linux 系统不很精通，因此目前对于我来说，建立这样一个环境唯一
的目的就是进行 phpdoc 的翻译工作，因此使用 Cygwin 是一个比较简便和经济的方式。
而且，Cygwin 完全可以完成 phpdoc 项目涉及的绝大部分（这里说“绝大部分”是为了
不失客观性，事实上到目前为止，我还没有在该系统下遇到任何无法满足的功能）操作。
加上 WinCVS 可视化的 CVS 操作界面，无疑给习惯使用 Windows 系统的我带来了方便。

    在您建立好了 CVS 的本地 repository 后，WinCVS 能够识别资源库下不同的文件，
把不同类别的文件用不同的图标表示，使您对庞大的目录结构一目了然。而且，它还会把
更改过的文件着成红色，在 commit 之后会把颜色再改回来。而且它支持外挂文本编辑器，
配合后文提到的 Editplus 使用，对于习惯 Windows 的用户来说，实在是方便。

    当然，该环境的推荐是仅针对那些对 Linux/Unix 系统不是十分熟悉，并更倾向于
在 Windows 环境下进行翻译工作的读者的。如果您是 Linux/Unix 高手或者是 M$ 的
反对者，我完全有理由相信以上 Dallas 的系统会更适合您。

    Editplus 是一款类似于 UltraEdit 的纯文笔编辑器，或许由于 Editplus 较
UltraEdit 出现的晚，老一辈的大虾们更倾向于使用后者；但本人经过长期使用 Editplus
进行 HTML/XML/SQL/PHP 的开发，认为它真的是一款非常值得推荐的编辑器。

    首先 Editplus 具有语法高亮，自动完成等现代文本编辑器的基本功能，更重要的
是，它除了自带一些流行语言（如C/C++、JAVA、VBScript、JavaScript、HTML、XML、
PHP、Perl、JSP、CSS）的语法高亮和自动完成以外，还有HTML、ASP 3.0、CSS 2、
PHP 4 等常用语言的元素库，以及 ANSI 和 控制字符的索引；您还可以自己定义新的
语法高亮和自动完成档，以及自己常用的 Cliptext。
    另外，Editplus 具有很强的开发环境样式定义，从折行方式到TAB字符到每级缩进
的字符数到语法高亮的具体颜色，使开发窗口最大程度上符合您的习惯；同时，可将保存
的方式在 PC/UNIX/MAC 之间切换，满足不同的需要。


==========================
  我的工作环境 － Jiania
==========================
最新编译环境,Windows+PHP+Phd+notepad++或是其它XML软件

  现在翻译php文档,不需要像上面所说的那样麻烦流程,只需在本地有php环境就行了
  建议 php5.3环境下使用!相关PHP安装略


  PhD 配制

  1.需要扩展
   1.1. libxml2
   1.2. xmlreader
   1.2. dom

  安装方法两种
  1.使用 PEAR Channel
  pear channel-discover doc.php.net
  pear install doc.php.net/phd-beta
  pear upgrade doc.php.net/phd-beta
  或是直接URL安装
  pear install http://doc.php.net/phd/PhD-0.2.3.tgz

  注:最新按第一种方法安装,可以获得最新版本


  2.使用CVS
  2.1
  cvs -d:pserver:cvsread@cvs.php.net/repository co phd
  cd phd
  pear install -f package.xml
  cd phd
  php build.php -d /path/to/phpdoc/.manual.xml

  2.2 编译phpdoc
   cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc-zh
   cd phpdoc-zh
   php configure.php
   phd -d .manual.xml


==========================
  我的工作环境 － Haohappy
==========================

翻译环境：
操作系统：Windows XP Professional
CVS 环境：TortoiseCVS 对应 (CVSNT) 2.5.03
编辑器  ：EditPlus

编译环境：
操作系统：Linux Fedora release 7 (Moonshine)
编辑器  ：VIM

把翻译和编译环境分开是为了在Linux下用crontable实现定期编译手册，但有时我
也会直接在Linux修改和提交文件。这两个平台都非常方便，按自己习惯选择即可。

在Windows平台下强烈推荐使用TortoiseCVS作为CVS作为客户端，操作非常方便。

我的编译过程和Jiania基本相同，补充两点：
1. 有时候可能因为手册章节中某些xml文件内容格式不对，无法生成.manual.xml，可以使用参数"--enable-force-dom-save"强制生成。
2. 如果想查看详细的出错原因，可以加上参数"--enable-xml-details"