9.4. Revision Tracking

Working on the translations is not just translating an English file and commiting 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 mailing list, or read the archives. If you never update your files, the translations can get useless. You should also subscribe to your languages 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.

9.4.1. The Translators Files

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              joe@hotmail.com
jane      Jane Smith           jsmith@yahoo.com
...

=============================================================================
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 http://cvs.php.net/. The web interface can generate really visual diffs, so you can easily spot what needs to be deleted, added and modified 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.

9.4.2. The Revision Comments

There is another way of tracking versions instead of using the method descibed above. You can decide yourself, as this is the better method for you or not. Some languages use the Revision comments and Translators files paralelly, 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 Translators example above. Now we spread the revision and association informations in the files mentioned there. Let's see what would be in the header of the bookinfo.xml file in this case:
<!-- EN-Revision: 1.16 Maintainer: jane Status: ready -->

You can see we loose 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 convinient now, as there are more then 4000 files in the English tree.

Currently all the three information is 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 loose the quick look on the whole list of your files. No, you do not loose 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 furter restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintaner. This HTML file gives you much more than the Translators file. See it yourself for 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, as build.log.gz is also there. See the Italian translation's file online: http://www.php.net/it/rev.

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):
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE translation SYSTEM "../dtds/translation.dtd">

<translation>

 <intro>
  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.
 </intro>
 
 <chmindex>
  This file was generated: <datetime/><br/>
  Go to <a href="http://www.php.net/download-docs">http://www.php.net/download-docs</a>
  to get the actual version.
 </chmindex>

 <translators>
  <person name="Joe Doe"     email="joe@hotmail.com"  nick="joedoe" cvs="yes" editor="yes"/>
  <person name="Jane Smith"  email="jsmith@yahoo.com" nick="jane"   cvs="yes"/>
  <person name="Joe Forever" email="joe@forever.net"  nick="joefo"  cvs="no"/>
 </translators>
 
 <work-in-progress>
  <file name="appendices/aliases.xml" person="joedoe" type="working"/>
  <file name="functions/dbx.xml"      person="joefo"  type="working"/>
 </work-in-progress>

</translation>
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. Assingning ready files may be needed if a time consuming update is in progress on that file.

There are two CHM format related things in this XML file. The first is the <chmindex> part, 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 <person> 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 <file>, 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 worked on one file, and not just the current maintainer. To achive 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 initally, but Jane followed him to be the maintainer):
<!-- CREDITS: joedoe -->
The credits comment can contain a comma separated list. These comments only affect the display of the translators table in revcheck.html.gz.

9.4.3. The Online Status Script

Rasmus Lerdorf developed on online status checking script. This script is most useful for files without revision comments, so if you use the Revision comments, use the specific script mentioned above.

You can access the script at: http://toye.php.net/~rasmus/status.php. Visiting this page, you need to wait for some time to generate, as it builds a whole table of file and dates information about all translations. If you would like to restrict the table to only one translation, you can provide the ?l=LANGCODE URL parameter, so to view the Hungarian status, visit: http://toye.php.net/~rasmus/status.php?l=hu.

This script tries to decide whether a file is up to date or not from the last modification date. The results are not correct if you modify your languages file, fixing typos, as this script thinks you modified the file to get in sync with the English one, and will mark your file as up to date. Although this script can help some to track files without revision comments, if you use revision comments, you can get more accurate results than this script, and much more than that.