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 2400 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 |
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 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
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> |
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
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.
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
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):
The credits comment can contain a comma-separated list. These
comments only affect the display of the translators table in
revcheck.html.
