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 PEAR documentation mailing list to get CVS commit messages, 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 one system for tracking the revisions and modification dates of the files in peardoc.
Instead of storing all responsibilities in a central file, the revision comment system stores them in the files they provide information about. Information about translator, revision numbers, and status information is stored in the revision comment. Let's see what would be in the header of the example file bookinfo.xml file in this case:
<!-- EN-Revision: 1.16 Maintainer: jane Status: ready --> |
We can see the revision number for the last english file used to update the translation (EN-Revision: 1.16), the translator cvs account name. 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 1300 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 full list of you files, you can go to the /peardoc/ directory and run:
./scripts/revcheck_pear.php xx > revcheck.html |
There are some optional extensions introduced for this script, 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 :
<?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" 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> |
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 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):
<!-- CREDITS: joedoe --> |