PHP手册翻译/编译指南[4]

Working on the translations is not just translating an English file and committing the results. Much of the work is needed to update the already translated ones, to get in sync with the content of the English files. To follow the modifications in the English tree, you should subscribe to the phpdoc , or read the archives. If you never update your files, the translations can get useless. You should also subscribe to your language's mailing list (if it's not English), to get CVS commit messages and participate in language specific discussions.

Updating a foreign language file can get difficult, as you may not know when and who translated that file, so you may not know where you should look for the updates needed. We have two (plus one) system for tracking the revisions and modification dates of the files in phpdoc. There is also a simple script to check parameters count/type/opt/reference in translated - scripts/check-trans-params.php.

Some translations are using a Translators file in the root of their translation's tree for revision tracking. This file can contain the names, email addresses, and CVS user names of the contributors of this translation, and the list of files translated.

Along with the XML file names, associations between translators and files, revision numbers, and status information can also be stored. One sample Translators file, for the imaginary xx language can look like this:

=============================================================================
CVS User  Name                 Contact email address
=============================================================================
joedoe    Joe Doe              [e-mail]
jane      Jane Smith           [e-mail]
...

=============================================================================
Filename                    Translator      Revision
=============================================================================
bookinfo.xml                jane            1.16
language-defs.ent           jane            1.7
language-snippets.ent       joedoe          1.8
preface.xml
------- appendices ----------------------------------------------------------
aliases.xml                 joedoe          working
debugger.xml
escaping.xml
history.xml                 jane            1.2
...

In this example you can see the listing of translators, and the first few lines of the list of files. Here you can store the assignment of the file, the revision number (what English file this translation was based on), and if there is no revision number yet, a status (eg. working).

When it is time to update a file (eg. the English bookinfo.xml jumped to 1.20 as time passed), you can ask for a diff between 1.16 and 1.20, and you'll see what modifications you need to port to the translated file. You can ask for diffs by using the diff CVS command, or using the web interface at . The web interface can generate really visual diffs, so you can easily spot what needs to be deleted, added, or modified, and where.

If you choose this method, do not forget to update the revision numbers stored in the Translators as you update files in your language's tree.

Note: This system is hard to maintain with the current phpdoc layout, as tracking the revisions of more then 4000 files in one text file can be very hard. Consider using the revison comment method described below, where you only need to work on one file if you make updates in your language.

There is another way of tracking versions instead of using the method descibed above. You can decide yourself, if this is the better method for you or not. Some languages use the Revision comments and Translators files in parallel, some use only one of these. It is better to decide, and not to use two systems, as things can get very messy this way.

Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Consider the example above. Now we spread the revision and association information in the files mentioned there. Let's see what would be in the header of the bookinfo.xml file in this case:

You can see we lose no information here, but we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely convenient now, as there are more than 4000 files in the English tree.

Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a CVS user name, or some nickname without a space, status can be anything without a space. Note, that this header is not updated by CVS (in contrast with $Revision, which is updated automatically). This is only updated when you edit the contents of the comment yourself.

You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. No, you do not lose this, but get much more! If you would like to build a list similar to the Translators file given above, you can go to the scripts directory and run:

./revcheck.php xx > revcheck.html

Here xx is the imaginary language code. After running this script you'll get a revcheck.html in the same directory. You can find revision comparisions and links to diffs for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer. This HTML file gives you much more than the Translators file. See it yourself for an example with the Italian translation (code: it). You can also easily run this with make revcheck in the phpdoc root directory, in case you issued a ./configure --with-lang=xx before.

As this system gets popular in many translation groups, the automatic build process also generates a revcheck.html.gz at the beginning of the build process for that language. It is available online in the languages manual directory. See the Italian translation's file online: .

There are some extensions introduced for this script, as need arised to port all contents of the Translators files to be available in this generated HTML page. This is why the translation.xml files are introduced. Here comes a simple translation.xml file for the imaginary xx language (contents ported from the Translators example above):

 
  This is some introductory text for the xx language translators
  about who is the manager of the translation, and where to find
  more information. This paragraph is printed on the top of the
  generated revcheck.html page.
 
 
 
  This file was generated: 

  Go to 
  to get the actual version.
 

 
  
  
  
 
 
 
  
  
 

As you can see, this file can store exactly the same content, as a Translators file. What is new in this file, is that you can add users without a CVS account, and can assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in the revcheck.html file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for all the translators. Assigning ready files may be needed if a time consuming update is in progress on that file.

There are two CHM format related elements in this XML file. The first is the element, where you can specify your text to display on the CHM index page, with a link to the actual versions. The editor parameter of a is also used in the grouping of translators on the CHM index page. These are optional, but are vital for every translation where the readers use the CHM format (all translations ;). Note that these are not used for current CHM manual generation, but will be important for the "next generation" CHMs, which are currently under heavy testing and development.

There are two optional parameters you can add to a , if you would like to record it: the date and revision. Date is assumed to be the date when the work was started, revision is the checked out revision of the English file used to start the work (denoted as CO-Revision in the generated table). There is currently no fixed format for the date parameter.

Another addon to this system is just to give credit to all people who worked on one file, and not just the current maintainer. To achieve this goal, we added the credit comments. One credit comment in eg. history.xml may look like this (in case Joe Doe translated the file initially, but Jane followed him to be the maintainer):

The credits comment can contain a comma-separated list. These comments only affect the display of the translators table in revcheck.html.gz.

Revision comments can be used also to print a diff between the current English file and the file used for the translation. Script scripts/diff_en_rev.php was created for this purpose.