Translate Toolkit & Pootle

Tools to help you make your software local

User Tools


This page refers to an old Pootle version. For those looking for the latest version, please follow these installation instructions.

System requirements

Your Pootle installation will need to be flexible enough to handle the translation load. If you want to host a lot of software e.g. multiple translations of large projects such as OpenOffice.org, Mozilla Firefox, GNOME or KDE we would recommend a minimum of:

  1. at least 512MB RAM, preferably 1GB or more (with multiple active projects, Pootle can easily use 300MB of RAM)
  2. enough disk space to hold the PO files for all the projects, plus some extra (20MB per copy of OpenOffice.org should be OK)
  3. at least a 2GHz processor

But of course if you are simply hosting one language or a number of languages for a small localisation project then you can easily use:

  1. 128 MB of RAM (Pootle itself will use up to 30MB with this quantity of data)
  2. Enough disk space to store your PO files
  3. a medium fast processor

Software Requirements

This section helps you choose the versions of software that you need, the dependencies and optional software. These might be slightly different if you are installing e.g. Windows so please familiarise yourself with your target platform and installation options before downloading all the software.

Pootle version choices

First choose the version most appropriate to your needs:

If you are a first-time user, you should be using the latest released version. For those who need problems fixed, or who want to work on the bleeding edge: you need to use Subversion.

Pre-requisite Software

Package Version Website Reason
Translate Toolkit 1.2.1 (usually the exact same version number as Pootle is required http://sourceforge.net/project/showfiles.php?group_id=91920&package_id=97082 Various functions
Kid 0.9.3 or newer http://kid-templating.org/ Templating
jToolkit 0.7.8 http://jtoolkit.sourceforge.net/snapshots/ Server engine
ElementTree 1.2.6 (if you are using Python 2.4) http://effbot.org/downloads/#elementtree Used by Kid for XML processing
Python 2.4 or later http://www.python.org/ Preferably 2.5
Xapian* * http://xapian.org/docs/bindings/python/ Indexing library to speed up searching
PyLucene* * http://pylucene.osafoundation.org/ Indexing library to speed up searching
zip* * Compressing downloads of PO file bundles
iso-codes* * any http://packages.debian.org/unstable/source/iso-codes Enables translated language and country names
python-levenshtein* * Provides speed-up when updating from templates

*Note: Kid 0.9.x depends on setup-tools, the kid installer has been configured to download and install setup-tools if the system doesn't have it. Unfortunately the ez_setup.py script kid uses is out of date and does not download the current available versions of setup-tools. (is this still true?)

* *Note: These packages are optional, but will provide some improvement.

You can download a kid installer for Windows (0.9.3) or follow this Installation Fix:

  1. Download a newer version of ez_setup.py, one can be located http://users.on.net/~var/code/ez_setup.py
  2. Replace the ez_setup.py script in the kid directory with the newer script

Optional Software

Package Version Website Reason
PyLucene Speeds up searching
Apache Proxying Pootle traffic
Version Control Software version_control integration

Obtaining the software from Subversion (version control)

If you want to try the bleading edge, or just want to have the latest fixes then you need to use Subversion to get your sources.

svn co https://svn.sourceforge.net/svnroot/translate/src/trunk

This wil retrieve Pootle trunk. To retreive a stable branch such as wordforge-0-10-branch, plus any pending fixes try:

svn co https://svn.sourceforge.net/svnroot/translate/src/branches/wordforge-0-10-branch 

Installation

You need to choose an installation method based on the system that you are running.

Single-click installation for most flavours of Linux

Klik is a single click installation system for packages which works on most flavours of Linux. There is a Pootle package for klik at http://pootle.klik.atekon.de/.

Installing from RPM

Download the source RPMs from the site above and rebuild using a command such as the following:

rpmbuild --rebuild Pootle-0.10-1.src.rpm

Or from the base directory of the untarred source file or subversion checkout run:

./pootlesetup.py bdist_rpm

Note you will probably also want to do this for jToolkit:

./jToolkitSetup.py bdist_rpm

This will create an RPM in the dist directory that you can install as follows:

su 
rpm -Uvh Pootle-0.10.rpm
rpm -Uvh jToolkit-0.7.8.rpm

Installation from DEBs

Debian roles packages for Pootle. So your best bet is to apt-get the latest Pootle and let Debian handle all your dependencies. If you want to stay on the cutting edge you will need to install from source and may want to use alien to allow you to install RPMs on your system.

Please notice that if you use this package, you should enable Pootle by editing the file /etc/default/pootle as explained in its comments; the service script will not work until you have modified this file accordingly.

Gentoo installation with Portage

EBuilds of Pootle and its dependencies are available. For more information, see the following bugzilla entry: http://bugs.gentoo.org/show_bug.cgi?id=153512

This ebuild hasn't yet been included in the default portage since it needs a Gentoo Developer to adopt the package.

Installing from source (tarballs or Subversion)

To install directly with no intermediate package management do the following. From the base directory of the untarred source file or subversion checkout run:

./pootlesetup.py install

You can do the same for jToolkit

./jToolkitSetup.py install

Installation as non-root

It's possible to install Pootle as non-root in, for example, your home directory or any other custom directory such as /usr/local/. Still, you need to have shell access to the Webserver and also to get in contact with the web admin to create the virtual host (VH) settings, as described below.

First create bdist installation packages. That is, run ./jToolkitSetup.py bdist and ./pootlesetup.py bdist respectively, for jToolkit and Pootle. Binary installation packages (in .tar.gz form) will be created in the dist subfolder of each program.

Unpack the binary installation packages in the destination directory. In our case is was:

$ cd /home/pootle/
$ tar xvfz /home/pootle/POOTLE/jToolkit-0.6.2/dist/jToolkit-0.7.8.tar.gz
$ tar xvfz /home/pootle/POOTLE/Pootle-0.6.0.20050518/dist/Pootle-0.10.tar.gz

The PootleServer script, that invokes Pootle, is placed as usr/bin/PootleServer while the rest of the files are placed in usr/lib/python2.3/site-packages/.

Now, add usr/bin/ to your PATH, and tell python where to find the jToolkit/Pootle python code. If your shell is bash or sh, run

export PATH=$PATH:/home/pootle/usr/bin/
export PYTHONPATH=/home/pootle/usr/lib/python2.4/site-packages/

or if you run tcsh or csh, run

set -l path = ( $path /home/pootle/usr/bin/ )
setenv PYTHONPATH /home/pootle/usr/lib/python2.4/site-packages/

You can now run PootleServer to start Pootle.

PyLucene (Optional)

Installating PyLucene is optional, Pootle will still operate as expected without this software installed. PyLucene makes use of the Lucene text indexing software. Pootle uses PyLucene to provide an effective and very fast way of indexing PO files. Searches become lightning fast.

Follow the instructions on the PyLucene home page which lists the software that should be downloaded and installed.

Installation on Microsoft Windows

Download and install the following, or newer, files:

It also asks for lxml:
http://pypi.python.org/pypi/lxml/2.1.2
Be sure to get the one for your version of Python.

Install Kid

  • Open it and extract the kid-0.9.3 directory using 7-Zip or similar product
  • Download and overwrite (where necessary) the following files into the extracted kid-0.9.3 directory:
  • Edit the setup.py script using your favourite editor (such as jEdit) and change the following line:
    install_requires=['elementtree']

    to:

    install_requires=[]
  • Open the command line (Click Start → Click Run → Type “cmd” (without quotes) → Click Ok)
  • Change your working directory to the kid-0.9.3 directory. For example, if your kid-0.9.3 directory is located in the c:\ then type:
    cd c:\kid-0.9.3
  • Type the following to run the setup script using Python:
    python setup.py install

Copy all the files inside the following directory:

C:\Python24\Lib\python2.3\site-packages\Pootle

to this directory:

C:\Python24\Lib\site-packages\Pootle

Open the command line (Click Start → Click Run → Type “cmd” (without quotes) → Click Ok)

Type the following command to start the server:

python c:\python24\scripts\pootleserver

(Please note that this is assuming you installed python as C:\Python24; if you used a different location, please change the paths above accordingly.)

Verifying your installation

Once you have installed Pootle succesfully, you can start the server by running

PootleServer

Run

PootleServer --help

for a list of command line parameters.

To verify which version of Pootle and dependencies you have installed run:

[l10n@server]# PootleServer --version
PootleServer 1.0
jToolkit 0.7.8
Translate Toolkit 1.0
Kid 0.9.5
ElementTree 1.2.6
Python 2.4.4 (#1, Oct 23 2006, 13:58:00)
[GCC 4.1.1 20061011 (Red Hat 4.1.1-30)] (on linux2/posix)

If you have difficulty installing please email the translate-pootle list with details of exactly what you did and what didn’t work. If possible, please include the output of PootleServer --version

Configuration

To start using PootleServer you need to have some initial configuration files, namely pootle.prefs and users.prefs. Samples, with extensive comments, are available in the Pootle package.

  • pootle.prefs --- contains the general configuration information for the Pootle server
  • users.prefs --- contains all user login information: name, hashed password, etc. This file is optional and if not present user information can be stored on pootle.prefs. For ease of maintanence it is recommended that you have two files.

The initial prefs files may be located in different places depending on how you installed the software. Looks in these places if you cannot find it:

/etc/pootle/
/var/pootle/
/usr/lib/python2.3/site-packages/

You can use a different pootle.prefs file by using the --prefsfile option.

PootleServer --prefsfile=/path/to/my/pootle.prefs

It is probably a very good idea to put your pootle.prefs file in a default location so that an upgrade with setup.py of the next version doesn't overwrite your existing files. Remember to back up these preferences just as much as you do with your PO files.

Startup User

When first running Pootle you need at least one user with siteadmin rights. users.prefs contains an example user startup with password startup who has siteadmin rights. You can enable this user by uncommenting the startup user in the file. It is very important that you remove this user before the site is made live.

Some preferences

Some of the things that you can change in the preference file, the actual file is very well documented.

  • If you are going to use email registration, you need to specify all the configuration options for email.
  • You can specify a non-default value for your base PO files directory.
  • You can specify which file to use for users' preferences.
  • You can easily setup all the initial languages without having to configure them all in the web interface. Configurations exist for many languages. You might only need to comment or uncomment the languages according to you preferences. The # sign indicates comments.
  • You can specify the default access rights to be used in all projects where no other access rights have been configured. For more information, see permissions.
  • If you want to let translators use an alternative_source_language while translating, you need to enable it server-wide. (available from version 1.2)