.. _intro-install:
====================
Installation Guide
====================
Before you can use Transifex, you'll need to get it installed. This guide
will guide you to a simple, minimal installation that'll work while you
walk through the introduction.
To avoid spending too much time talking about packaging systems, this guide
is based on yum and Fedora. You can substitute those commands with your own
distribution's packaging system commands.
First things first
==================
Who should consider installing Transifex?
-----------------------------------------
Good question!
Transifex is a web system for managing complex translation projects and serving
files to a community of translators. You can see it live at
Transifex.net_, our hosted, upstream version of Transifex common for any
project which chooses to start receiving translations in a snap. This instance
is managed by Indifex_, the company sponsoring the development of Transifex.
So, who would be interested in installing Transifex on their systems?
Project maintainers
~~~~~~~~~~~~~~~~~~~
If you're the administrator of a project or community, then you need to decide
whether you would like to setup your own, self-hosted instance of Transifex,
or use an upstream, hosted one such as Transifex.net_ or one of the other
`public servers`_ available.
The users who usually consider installing their own instance are communities
with lots of projects (hundreds) and complex translation workflows. This
translates in setting up Tx on one's own servers and growing a local community
of translators instead of using an upstream pool of translators. This choice
gives control and freedom to manage the server, however it implies an isolated
translation community and higher maintenance costs.
The alternative of a self-managed version is using a common, hosted instance.
This allows the sharing of a larger translation community, lower management
overhead, and sometimes some extra features available there.
Translators
~~~~~~~~~~~
If you're a translator, you're probably *not* interested in installing
Transifex itself. Transifex serves the purpose of the *server*: It distributes
translations pulled from a number of upstream projects to people. Currently,
you can interact with Transifex using your every-day browser, and there is
no specialized Transifex client you can install.
Now that we've made clear who we're talking with, let's proceed in explaining
how a private installation of Transifex can be set up.
I'm ultra hardcore. Give me just the gist!
==========================================
The following is what a set of super-fast installation instructions would look
like (run as root or under ``sudo``)::
yum install python python-setuptools python-imaging
yum install cvs subversion pysvn mercurial git bzr bzrtools python-urlgrabber
easy_install transifex
Please note that the above might eventually end up missing something compared
to the full instructions below.
Installing Basic Dependencies
=============================
Python
------
Being a Python tool, Transifex requires Python. We recommend
installing Python 2.5 or later.
You can get Python at http://www.python.org/, or from your favorite
distribution. If you're running Linux or Mac OS X, you probably already have
it already installed.
You can verify that Python's installed by typing ``python`` from your
shell. You should see something like::
Python 2.5.1 (r251:54863, Jun 15 2008, 18:24:51)
[GCC 4.3.0 20080428 (Red Hat 4.3.0-8)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
A note on ``PythonPath``
~~~~~~~~~~~~~~~~~~~~~~~~
These applications can be installed anywhere on your system, as long as Python
can find them. Python uses the ``PythonPath`` environment variable for this.
The value you use for ``PythonPath`` should include the parent directories of
all the modules you are going to import in your application. It should also
include the parent directory of Transifex itself.
This is exactly the same situation as
setting the Python path for interactive usage. Whenever you try to import
something, Python will run through all the directories in ``sys.path`` in turn,
from first to last, and try to import from each directory until one succeeds.
An example might make this clearer. Suppose you have some applications under
``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and
so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have
specified DJANGO_SETTINGS_MODULE_ as in the above
example. In this case, you would need to write your ``PythonPath`` directive
as::
PythonPath "['/usr/local/django-apps/', '/var/www'] + sys.path"
With this path, ``import weblog`` and ``import mysite.settings`` will both
work. If you had ``import blogroll`` in your code somewhere and ``blogroll``
lived under the ``weblog/`` directory, you would *also* need to add
``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the
**parent directories** of anything you import directly must be on the Python
path.
Version Control Systems
-----------------------
To run Transifex you probably need some versioning systems. By default
Transifex only requires Mercurial (hg). Depending of which ones you want to
use, you will need to install some of the following packages:
* Bazaar (bzr)
* CVS (cvs)
* Git (git)
* Mercurial (hg)
* Subversion (svn)
Since the above are probably available from your distribution, you can use
its own tools to install them. On Fedora you can run the following command::
yum install cvs subversion pysvn mercurial git bzr bzrtools
If you're enabling the tarball support, you also need 'urlgrabber'::
yum install python-urlgrabber
Installing Transifex
====================
There are three basic ways to install Transifex:
* Using Python's packaging tools (stable version)
* Using your distribution's packaging tools (stable version)
* Pulling directly from our development repository (stable and development
versions)
Install using Python's setuptools
---------------------------------
Probably the easiest way to install Transifex is by using Python's common
packaging tools. Since Tx is registered on the Python Packaging Index and
has defined its own Python dependencies, using this method to install all the
required software is quite easy.
First off, you'll need the following packages installed::
yum install python-setuptools python-imaging
.. note::
If ``python-imaging`` isn't available in your packaging system, just install
``gcc`` and the following command will pull and auto-compile this package for
you.
By default, ``easy_install`` installs the software in your system's standard
Python packages directory (eg. ``/usr/lib/python2.5/site-packages/transifex``).
If you want to do this, running the following as root or with sudo, should
do the trick::
easy_install transifex
Using a virtual environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, you can setup a virtual environment using ``virtualenv``, and
isolate your Transifex installation in its own "shell". This is particularly
useful for testing Tx, for "freezing" Tx's dependencies, and, your best choice
if you don't have root access on the system.
A set of commands similar to the following will create a virtual environment
in the current directory and install Transifex in there::
sudo easy_install virtualenv # or: sudo [yum] install virtualenv
virtualenv txenv # create the environment
source txenv/bin/activate # switch in using it
easy_install transifex # nstall Tx in the virtual env
For more information on this way of installing Tx, please refer to the
documentation of virtualenv itself.
If you've already installed the non-Python dependencies (like some of the
versioning systems you might use) mentioned in the previous sections, you could
jump to the `Initial configuration`_ section to proceed in configuring your
setup.
Install using your distribution's tools
---------------------------------------
Transifex has been packaged in a number of Linux distributions. You can check
your distribution's packaging system to see if it is available in yours::
$ yum info transifex
Available Packages
Name : transifex
Arch : noarch
Summary : A system for distributed translation submissions
URL : http://transifex.org/
License : GPLv2
Description: Transifex is a web-system that facilitates the process of submitting
: translations in remote and disparate version control systems (VCS).
If Transifex is available for your distribution, you can proceed by installing
it just like any other package. In the case of Fedora, the software is split
in two packages, and can be installed as follows::
yum install transifex transifex-extras
To configure your setup, proceed to the `Initial configuration`_ section.
Install manually
----------------
You can get the source code in a number of ways.
Getting a stable version
~~~~~~~~~~~~~~~~~~~~~~~~
Stable releases are available from the following location(s), in addition to
alpha, beta, and release candidates:
- http://transifex.org/files/
- http://pypi.python.org/pypi/transifex
Tarball are source packages, whereas eggs are binary distributions for a
specific version of Python.
Getting a development version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Our development tree is kept pretty stable at all times. This is achieved by
reviewing patches before they are submitted, and by having very few core
committers. However, you should keep in mind that while the code is stable,
the database schema isn't. During the development of a major release, the
DB structure (Django models) change rapidly, so you'll need to evolve your
schema quite often using our out-of-the-box migrations.
Knowing the above, feel free to jump right in and install a development
version from our Mercurial repo and enjoy our newest and greatest features.
The current development version of Transifex can be fetched by cloning the
mainline repository::
hg clone http://code.transifex.org/mainline transifex
From here you can also switch to stable versions, which are tagged
appropriately::
cd transifex
hg tags
hg update <tag>
To grab a branched development version of Transifex, you can navigate to
http://code.transifex.org/ to see the active branches.
Install dependencies
~~~~~~~~~~~~~~~~~~~~
Django
::::::
Transifex is developed on top of a Python Web Framework called Django. We
recommend installing the latest version of Django, but anything above 1.1
should do. You can get more information about how to install Django on
your system from the official Django documentation.
Usually you can use the package your distribution provides you::
yum install Django
.. _install-django-deps:
Python dependencies
:::::::::::::::::::
This is the generic method for creating a development environment for
Transifex. We strongly suggest running those commands inside a virtualenv
environment instead of running them as root. For an example of a Virtualenv
setup, take a look at the `Virtualenv example`_ wiki page. You can also
install some of these dependencies as packages in your distribution, if they
are available.
.. code-block:: bash
easy_install Markdown httplib2 pygments>=1.0 polib>=0.5.1
easy_install pygooglechart
easy_install django-pagination django-notification django-authority \
django-piston south>=0.7 django-sorting django-filter django-staticfiles \
django-addons
easy_install -f http://transifex.org/files/deps/ contact_form \
django-tagging userprofile django-ajax-selects \
django-threadedcomments>=0.9
easy_install -f http://effbot.org/downloads/ Imaging==1.1.6
Non-Python dependencies (like versioning systems) need to be installed with
traditional ways (like your system's packaging mechanism).
Translation-specific packages
:::::::::::::::::::::::::::::
Transifex requires a couple of standard packages to support translations.
Currently these are the following:
* gettext (standard Internationalization library)
* intltool (for dynamic ``POT``-file generation)
On Fedora you can run::
yum install gettext intltool
Initial configuration
=====================
Initialize the database
-----------------------
After you have all dependencies and packages installed, the Transifex
installation should be very simple. Customize ``settings/*.conf`` and
``urls.py`` to accommodate your server's needs.
To enable Transifex's notifications you'll need to switch the relevant setting
called ENABLE_NOTICES to ``True``.
To have your widget code viewable from outside your transifex instance you have
to set your ``STATIC_URL`` variable to an absolute URL (by using relative paths
you can still view the widgets on your own installation)
.. note::
Ensure the database server defined in the settings files is properly
configured and running, and that your selected database is using UTF-8.
Depending on the backend, this is achieved in different ways; for example,
in MySQl, you might want to modify ``my.cnf`` or create the database with
a command similar to the following:
.. code-block:: sql
CREATE DATABASE db_name DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
For more information refer to the Django Documentation Section
"`Creating the database`_".
Once you're done configuring, run inside the project directory::
./manage.py txcreatedirs # Create necessary directories
./manage.py syncdb # Setup DB tables, create superuser
./manage.py migrate # Setup more DB tables
./manage.py txcreatelanguages # Create a standard set of languages
./manage.py txcreatenoticetypes # Create a standard set of notice types
./manage.py build_static # Copy all the addons files to the static dir
./manage.py runserver 8088 # Start the development server
The first command will create the necessary directories on the disk. Note that
the user you're running the software as, needs to have write access to these
directories (check out your configuration files to see what these are).
``syncdb`` will create the database tables, and ask you to create an admin user
(superuser), who will have access to the admin panel. The latter is by default
accessible through ``/admin/``, something you can customize by modifying the
file ``transifex/urls.py``.
Now, you can fire up your browser at ``http://localhost:8088/``, grab a cup of
coffee and lean back.
Import some data
----------------
Transifex uses the fixtures feature of Django to load some initial data in the
database. The following commands require you having run ``./manage.py syncdb``
at least once before in order for the database tables to exist.
The following commands loads a bunch of sample data to play around with.
.. code-block:: bash
./manage.py loaddata txcommon/fixtures/sample_data.json
./manage.py loaddata txcommon/fixtures/sample_users.json
The last command created two users: 'guest' and 'editor'. The 'guest' has the
basic rights of a logged-in user of the site, while the 'editor' account has
more advanced privileges like modifying projects, etc. Together with the 'admin'
user created with the 'syncdb' step above, you should have 3 accounts now, each
with its own access level.
You can now fire up your browser to check out the newly imported data.
Note that the registered projects have not been actually checked out by
Transifex yet. To have translation files downloaded and fresh statistics
produced, run a fresh checkout::
./manage.py txstatsrefresh
This command is usually used in a cronjob to refresh Transifex's cache and
translation statistics every once in a while for translators.
Internationalization (i18n) support
-----------------------------------
To be able to use Transifex with a localized interface, it is necessary to
create the translations objects files (.mo) using one of the following commands,
for example:
.. code-block:: bash
./manage.py txcompilemessages -l pt_BR
or
./manage.py txcompilemessages
At this point you're ready to read about :ref:`running Transifex <intro-running>`
to proceed to further customization of your instance.
Debugging
=========
Debugging is enabled through a separete ``SETTINGS`` file, which enables some
additional applications and features. Some of these additional applications
might require installation using ``easy_install``, but you can enable any
number you want by editing the ``settings_debug.py`` file.
Some of these applications define their own models, so the first time you'll
use the file, a 'syncdb' using that file will be needed to have the respective
database tables created::
./manage.py syncdb --settings settings_debug
From that point on, you can run the debug server as follows::
./manage.py runserver --settings settings_debug
Testing
=======
For testing the whole project you can run::
./manage.py test
For testing a specific application inside Transifex you can run::
./manage.py test projects
Alternatively, by installing the ``django-nose`` package, the following command
can prove useful::
nosetests --with-django <location-of-test-file>
.. _public servers: http://transifex.org/wiki/ProjectsUsingTransifex
.. _Transifex.net: http://www.transifex.net/
.. _Indifex: http://www.indifex.com/
.. _DJANGO_SETTINGS_MODULE: http://docs.djangoproject.com/en/dev/topics/settings/#django-settings-module
.. _`Virtualenv example`: http://transifex.org/wiki/Development/InstallationOnCentOS_VirtaualEnv
.. _`Creating the database`: http://docs.djangoproject.com/en/dev/ref/unicode/#creating-the-database
