Serge + Pootle

IMPORTANT: This guide is kept for historical reasons; Pootle open-source project is no longer maintained by the open-source community, so for new installations we recommend using Zing.

Configuring Serge to work with Pootle

Here are the main steps that you will need to make Pootle work together with Pootle.

Initial Pootle Configuration

It is recommended that you install both Serge and Pootle on the same dedicated localization server which will be accessible by your translators. Once you install Pootle (please follow its own installation instructions), you will need to specify the root directory where Pootle expects all translation files to be stored, in its configuration file (typical installations will use ~/.pootle/pootle.conf):

Below is an example of the file structure that Pootle would expect under /var/serge/po directory:

Pootle can have multiple translation projects, each having its own unique identifier, which also serves as a folder name. In our example above, it's project1 and project2. Inside each project, Pootle expects a set of directories named after target translation locales, e.g. de, ja, pt_BR and so on. Inside each locale directory, there can be a number of translation files (Serge uses .po file format for such files).

Configuring Serge Jobs

In each of your Serge jobs, you need to configure ts_file_path parameter so that it generates .po file at a proper location (here and below we will assume we're working with project1 project and our configuration file is conveniently named project1.serge):

Notice that we use %LOCALE% macro here to generate locale-specific folders under /var/serge/po/project1/ directory. For this macro to generate proper locale names, it is recommended to specify destination languages in their "canonical" form, where language name is a two-char ISO 639-1 language code optionally followed by dash and a two-char ISO 3166-1 country code. In Serge, it is recommended to use a lowercase version of the language, as macros like %LOCALE% will properly adjust the case:

Once you set up the jobs in your configuration file, you can run Serge localization pass once to see if the .po files are generated properly, and the folder and file structure matches the expectation:

Registering a Project in Pootle

In order to appear in the translation interface, every new project needs to be initially registered in Pootle. You, as a Pootle administrator, need to go to Pootle's Admin interface, select Projects tab, create a new project there and specify the project id, e.g. project1. This will tell Pootle that the project files are located in /var/serge/po/project1/ directory. Pootle will scan files in there and publish the project for translation. In addition to specifying the project id, you need to give the project its display name, e.g. "Project 1", and leave default values for other parameters.

Configuring Serge Synchronization

For Serge to be able to communicate with Pootle, Serge config must have the following sync → ts section:

Here we specify that we want to use pootle translation service plugin, and provide two parameters:

1. manage_py_path is the path to manage.py script that comes with Pootle and serves as a command-line API for the local Pootle instance;
2. project_id is the same project identifier as the one we used in previous step.

Note that if you install Pootle using pip install Pootle, the manage.py script might actually be named pootle, so refer to Pootle documentation. Also, if you install Pootle into a virtual Python environment, you may need to write a simple wrapper script that selects this environment and then calls manage.py (or pootle) with all command-line parameters, and use the path to this wrapper script as a value of manage_py_path. This will allow Serge to run the script from within a proper environment.

Once this is configured, you can run the following commands to push changed .po files to Pootle and pull translations back from Pootle into .po files:

Putting It All Together

Here's the combined structure of the Serge configuration file that you can use as a template: