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 mailing list, 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 <methodsynopsis> - 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 [email protected] jane Jane Smith [email protected] ... ============================================================================= 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. 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, 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 Translators 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:
<!-- EN-Revision: 1.16 Maintainer: jane Status: ready --> |
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 |
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: 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="[email protected]" nick="joedoe" cvs="yes" editor="yes"/> <person name="Jane Smith" email="[email protected]" nick="jane" cvs="yes"/> <person name="Joe Forever" email="[email protected]" 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 CHM format related elements in this XML file. The first is the <chmindex> 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 <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 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 --> |
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.