Serge + Zing

Zing is a free open-source web-based translation server. Zing was designed to seamlessly work with Serge and support all of its features, and is our recommended translation front-end. Zing supports working with both community and paid translators.

Configuring Serge to work with Zing

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

Initial Zing Configuration

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

Why /var/serge/data/ts? Technically, you can set up any directory to exchange files between Serge and Zing. In this guide, we try to follow the suggested canonical directory structure for your Serge installation. See Organizing your data.

Below is an example of the file structure that Zing would expect under /var/serge/data/ts directory:

Zing 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, Zing 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 in an arbitrary folder structure (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/data/ts/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 Zing

In order to appear in the translation interface, every new project needs to be initially registered in Zing. You, as a Zing administrator, need to go to Zing's Admin interface, select Projects tab, create a new project there and specify the project id, e.g. project1. This will tell Zing that the project files are located in /var/serge/data/ts/project1/ directory. Zing 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 Zing, Serge config must have the following sync → ts section:

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

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

Note that if you install Zing into a virtual Python environment, you may need to write a simple wrapper script that selects this environment and then calls the original zing executable with all command-line parameters, and use the path to this wrapper script as a value of executable config parameter. 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 Zing and pull translations back from Zing into .po files:

Putting It All Together

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