Pootle: a web translation and translation management engine
===========================================================

* How it works
* References
* Requirement/Installation
* Running
* Bug reporting
* Notes
* Assignments

How it works
------------
The concept is: a PO file is a document, so lets use PO files directly, 
rather than storing it in a database.  But we need quick access to statistics 
so we cache them in .stats files. This lets us do most checks etc. in advance 
and then iterate quickly.

References
----------
Bugzilla: http://bugs.locamotion.org/
Wiki: http://translate.sourceforge.net/wiki/pootle/index
Mailing List: https://lists.sourceforge.net/lists/listinfo/translate-pootle
  translate-pootle@lists.sourceforge.net
Mail Archives: http://sourceforge.net/mailarchive/forum.php?forum=translate-pootle

Requirements
------------
Please read http://translate.sourceforge.net/wiki/pootle/installation for the 
lastest instructions.

Pootle requires the Translate Toolkit package from 
http://translate.sourceforge.net/
Note all the optional dependencies of the Translate Toolkit for optimal 
performance and functionality in Pootle.

The Translate Toolkit requires Python 2.3 or higher, but Pootle itself only
works with Python 2.4 or higher.  The Translate Toolkit must be installed 
properly i.e. it needs to be accessible in your Python Path. This will normally
be accomplished by installing from source:

  python setup.py install
  
If you get this error along the lines of
Unable to open /usr/lib/python2.N/config/Makefile (no such file or directory)
while running setup.py, you need to install python-dev or libpython2.N-devel
package. Try to install python2.N-dev or libpython2.N-devel or something 
similar with your distribution's package manager.

For the web interface, Pootle requires Django 
(http://www.djangoproject.com/)
Django applications can run under Apache using mod_python or mod_wsgi,
but they're also bundled with a standalone webserver that can be run
from the command line.  Pootle works equally well on all Django
deployment scenarios, standalone server is the easiest to set up and
get running.

To run Pootle you need to have Django 1.0 installed properly

       tar xzvf Django-1.0.2-final.tar.gz
       cd Django-1.0.2-final
       sudo python setup.py install

you can also install Django using easy_install
      
  easy_install django


ZIP is needed to enable users to download ZIP files of directories. For 
integration with CVS and/or Subversion, the relevant version control client 
must be installed and accessible from the PATH.

From version 0.9 of Pootle, kid (http://kid.lesscode.org/), and elementtree
(http://effbot.org/downloads/#elementtree) are also needed.  Elementtree is
not needed anymore with Python 2.5.

To install "elementtree", run
  tar xvfz elementtree-N.N.N.tar.gz
  cd elementtree-N.N.N
  python setup.py install
  
To install kid, run
  tar xvf kid-N.N.N.tar.gz
  cd kid-N.N.N
  python setup.py install
  
For Debian users: if you do not have setuptools installed, try:
  apt-get install python2.N-setuptools
or
  wget http://files.turbogears.org/eggs/setuptools-0.6a11-py2.4.egg

Installation of an indexing engine (PyLucene or Xapian) is optional, but helps
to speed up searching. Note that Xapian is incompatible with Apache,
Pootle will not enable Xapian indexing if running under mod_python or mod_wsgi


Installation
------------
This is a Beta release of Pootle, and it is still far from ready, so
for the moment we do not recommend installing Pootle, but rather
running it directly from the source code directory. 

However you still need to prepare the pootle database.

Extract Pootle's source code, then change directory to inside the
Pootle dir

        tar xvf Pootle-1.3.0-beta2.tar.gz
           cd Pootle-1.3.0-beta2

Run the following commands to create and initialze the Pootle
database, and prepare stats and search index for initial translation projects

           ./manage.py syncdb
     ./manage.py initdb
     ./manage.py refresh_stats


Running
-------
To run Pootle just change directory to inside the pootle directory
(that is, cd /my/installation/path/Pootle), then simply execute

      ./manage.py runserver

You can specify which port to run under (by default it's 8000)

      ./manage.py runserver PORTNUMBER

Use --help to see the other options. The defaults will 
generally work.

Now visit http://localhost:8000/ and begin translating.

To stop, press Ctrl-C. 


Pootle can run under Apache using mod_python or mod_wsgi, but this
requires modifications to Apache's config files, check
http://translate.sourceforge.net/wiki/pootle/running_under_apache for
detailed instructions


Bug Reporting/Feature requests
------------------------------
You can always report bugs or feature requests on the mailing list but because
of the increase in users and the fact that bug reports do go missing it is
probably best to place your bug report in Bugzilla: http://bugs.locamotion.org/

If you have a traceback or a patch then please include it. Also please be quite
specific about how the bug occured and what you expected to happen.

If this is a feature request then try to be specific about how you think this
feature should work.

Notes
-----
Files should be reindexed automatically.
To reindex manually, simply remove any stats files you want reindexed, or run 
  ./manage.py refresh_stats

Assignments
-----------
To assign sstrings to users, you need to create a xxx.po.assigns file in the same 
directory as xxx.po This should contain lines in the following format:

username: action: 0,2-34,36,99

where action can be 'suggest' or 'review', and the numbers refer to 0-based item 
numbers in the file.