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
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
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
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.
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
Here comes a simple
for the imaginary xx language :
In this file, 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
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 optional parameters you can add to a <file>,
if you would like to record it: the
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
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
history.xml may look like this (in case
Joe Doe translated the file initially, 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