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 mailing list, or read the archives. If you never update your files, the translations can get useless.
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.
Nearly all translations are currently using a Translators file just in the root of their translation's tree. 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 ... |
When it is time to update a file (eg. 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.
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 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.
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 (as $Revision is updated automatically). This is only updated when you edit the contents of the comment.
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 |
As this system gets popular in many translation groups, the automatic build process also generates a revcheck.html at the end 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/manual/it/revcheck.html.
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> <translators> <person name="Joe Doe" email="joe@hotmail.com" nick="joedoe" cvs="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> |
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).
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 --> |
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.