The mechanisms of the Translation Project
-----------------------------------------

This README briefly describes how things are set up on the server of the
Translation Project.


Website
-------

For serving the pages of the Translation Project website, Apache is configured
in /etc/apache2/sites-available/translationproject.org like this:

  <VirtualHost *>
    DocumentRoot /home/translation/site
    ServerName translationproject.org
    ServerAlias *.translationproject.org
    RedirectMatch permanent ^/$ http://translationproject.org/html/welcome.html
  </VirtualHost>

The 'RedirectMatch' redirects any request for the root page of the wesite
(translationproject.org/) to the welcome.html page in the html/ subdir.

The documentation pages are produced by running 'make site' in the ~/progs
directory; the source for these pages is located in ~/progs/webgen.  The
team and domain pages are generated by running 'generate-static-pages -t' and
'generate-static-pages -d'.

PO statistics
-------------

The file ~/cache/postats contains most of the data needed to produce the
domain and team pages.  This postats file gets updated by 'po-register',
which is run by an admin when a new POT file is added to the archives, or
run by 'tp-robot' when a translator has submitted an updated PO file.


The robot
---------

The user 'tp', that receives all mail sent to <*@translationproject.org>, has
among other things the following entry in its '.procmailrc' file:

    # Ignore the To line, just look for "TP-robot" at the
    # start of the Subject line, as an anti-spam measure.
    :0:
    * ^Subject: *[Tt][Pp][-_ ][Rr]obot
    bot-queue

This rule filters all mail that is meant for the robot to the 'bot-queue'
mailbox.  To handle the queue, the 'tp' user has this 'crontab' entry:

    0-50/10 * * * *	/bin/sh /home/tp/progs/bin/run-queue.sh

This runs 'run-queue.sh' every ten minutes.  That script is what actually
launches the robot for each received file.  The robot extracts the PO file
from the email, runs several checks on the file, and sends a report back
to the submitter.  If the PO file is good, it hands it to 'po-register',
which adds the file to the archives, adds a symlink to it in the latest/
subdir when appropriate, calls 'calc-postats' to calculate the statistics
for the file and put these in ~/cache/postats, regenerates the affected
team and domain pages, and sends out an email to the mailing list of the
corresponding language team, and also to the maintainer (but only when
the submission was for the most recent POT file).

The robot will skip its scheduled run when an admin is busy running
'po-register' or 'calc-postats' by hand, to prevent them from both accessing
the postats file at the same time, overwriting the results of the other.


Adding a new POT file
---------------------

When package maintainers submit the URL of a new version of their package,
a TP admin cd's to progs/registry, edits the registry.sgml file to update
the <url> field of that package, runs 'make' in that dir (to create a digest
of the registry in ~/cache/), and then runs 'fetch-pot $DOMAIN'.  If that
succeeds, which it normally should, she runs 'po-register $DOMAIN-$VERSION.pot'
-- this runs 'msgmerge' with the new POT on the most recent PO file for each
language, sends out notifications of the newly created PO files to the teams
and to the last translators, and sends a confirmation to the maintainer.


Removing PO files
-----------------

When a package has become obsolete, a TP admin first moves or removes all
the corresponding POT and PO files, then runs 'calc-postats -duv' to delete
the stats for those files from the statistics database, then removes the
domain plus all its assignments from the registry.sgml file, and finally
regenerates the team pages with 'generate-static-pages -t'.


Changing translator details
---------------------------

When a translator takes on a new package, or a new translator has joined a
team, a TP admin cd's to progs/registry and edits registry.sgml, to add or
change the required tags.  After that she runs 'make' in that directory to
update the registry digest in ~/cache/, and runs 'generate-static-pages'
with the teamcode as an argument to update the team page.


If anything is missing from this file, please report it to
<comments@tranlationproject.org>.

Installing a (test) system
--------------------------

Unpack the tar-ball or clone the repository into a directory, say it's called "TP".
Create TP/Makefile.local and set the variables

sitedir  = <path to html directory>
htmldir  = $(sitedir)/html
extradir = $(sitedir)/extra
cachedir = $(sitedir)/cache

also edit the file lib/config.py (TODO: be more clear about this).

then run
make install-test-system

This will create all necessary files. You can edit
registry/registry.sgml and registry/AUTHORS now to turn this into a
"real" installation.