Translate your Web application with Weblate [Part 1] - Installation

The problem

We would like to maintain translations on a globally-scaled application with multilanguage support. Lets say that our platform is Symfony (very popular these days) and we are using one of the default type of translations in Symfony - YAML files. We can say that our platform is already in some point of development and we have many YAML translation keys and domains as well as some different language version [English, French etc.].

We need to choose a good tool which will be easy to use by translators (or any other content-management people) and also have some functionalities to simplify the whole process.

We want our output format to be Gettext (for some obvious reasons) and make it fully work on a version management to solve a lot of problems with conflict and working on similar keys.

Acceptance Criteria

We have a variety of tools that can be used and each one has some pros and cons. I will use great Weblate for this particular solution.

Lets go first with our sample configuration on which I have based most of my decisions about the tool:

  • PHP with Symfony 2
  • Yaml translations (in app/Resources/translations)
  • Different domain files (messages.en.po, about-us.en.po etc.)

And our output expectations:

  • Gettext files used (.po, .pot)
  • CVS for translations management (in this example we will use git)
  • Platform on which translators can work on

Solutions

Installing Weblate

We are considering solution for large-scale application so as I suggested on the blog tutorial with nginx it's worth to have a separated machine to avoid any problems with security and packages dependency issues on the OS.

Weblate installation process can be a little complicated for some of you who had no previous experience with Pythons' Django framework so I will go through the process quickly.

To make the installation easy and fast we have to fulfill following requirements

Full requirements can be found on Install Docs from Weblate - remember that not all of them are really required - for example libravatar or python-social-auth can be easily ommited without any harm.

I recommend using virtualenv to not mess in the global Python installation but I will omit it for article readability reasons

$ git clone https://github.com/nijel/weblate.git
$ git checkout weblate-2.3
$ cd weblate/
$ cp settings_example.py settings.py # do not mv ;)!

The default config should work for now but you will have to edit it before going live.

Now we need to install all Python dependencies that Weblate requires - nothing easier!
You will need pip (for Mac you may need to do easy_install pip)

# ensure you are in the main directory
# not in weblate/weblate
$ pwd
/home/gachu/weblate/
$ pip install -r requirements.txt
[... successful commands ...]
$ ./manage.py migrate # db migration (default sqlite3)
$ ./manage createadmin # for admin user creation
Creating user admin with password u7Mu6HA#S^3E8
$ ./manage.py runserver 127.0.0.1:8123

IP and port is optional and when not given it will fire on localhost:8000.

Migrating to PO files

Migration to PO files can be little tricky. I will use great Loco Conversion tool for this purpose. If you have some very big files its worth to find a script on github which will do the work.

Lets say we have a sample YAML files and domains:

[@messages.en.yml file]
  datetime.today: today
  datetime.yesterday: yesterday

[@messages.fr.yml file]
  datetime.today: "aujourd'hui"
  datetime.yesterday: hier

[@about-us.en.yml file]
  about.title: Hello my friends, we are awesome
  about.content: <b>Something more</b>

[@about-us.fr.yml file]
  about.title: Bonjour mes amis, nous sommes génial
  about.content: <b>Quelque chose plus</b>

If we put them on Loco Conversion tool we have to configure source language and translation language. For me, English is the default one so for en.yml files I have left the Translation language: field empty. For French I set it to French. Do not forget to set output format to gettext PO.
Output files look like this (some headers removed for readability):

[@messages.en.po file]
msgid ""
msgstr ""
[...]
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-07-16 22:51+0100\n"
"PO-Revision-Date: 2015-07-16 22:51+0100\n"
"Last-Translator: \n"
"Language-Team: \n"
"Language: English\n"
"Plural-Forms: nplurals=2; plural=n != 1;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
[...]

msgid "datetime.today"
msgstr "today"

msgid "datetime.yesterday"
msgstr "yesterday"

and similar for French. About us domain file saved as about-us.en.po and about-us.fr.po.

Weblate configuration

Go to http://127.0.0.1:8000/admin/ and add a project below Trans -> Projects

It's worth to check Push on commit checkbox.

Before you go to the next thing

Prepare an empty Git repository somewhere. You will need to have SSH keys prepared. Add the just created PO files to the repository (for Symfony leave them in the root dir /). In Weblate Admin Panel (http://127.0.0.1:8000/admin/ssh/) add your SSH key to allow Weblate push and pull from it.

After that go back to Django Admin Panel at /admin and add a Sub project (or Component in newest version).

  • Set Component name to name of your file domain.
  • Set Project to just created project
  • Set Source code repo and Push repo to repo that we have just created. Remember to use ssh protocol.

  • Set File mask to <fileDomain>.*.po (* goes for the language code)
  • Set Monolingual base lang file to your base lang file (in my case it was messages.en.po)
  • Set File format to Gettext PO file (monolingual) [we will use English PO file as Source lang file - not POT files]

  • Set New language to No adding of language - this is for security reasons. In many cases you don't want translators to add new languages and it probably will require some development work anyway.
  • Set Merge style to Merge (Rebase can be risky).

You have to repeat this Subproject (Component) creation for EACH file domain! (about-us, messages, etc.)

If your PO files are very big you will probably need to wait a lot of time before the Subproject is added - if it takes too long it's worth to check the ./manage runserver command log - sometimes you can have some problems withssh key or other access problems (possible PO parse problems).

Main Weblate Project view

Weblate subproject view

Weblate sample translation view

What next?

Of course this is not all what we can do in that matter - there are plenty of things to setup before Weblate will be usable by our translators.

In the next part I will explain how to:

  • Connect translation repository to our Symfony project and how to manage it
  • Configure Weblate emailing with Google Gmail or any other provider
  • How to prepare Weblate to production environment e.g.
    • How to move from sqlite3 to mySQL
    • How to configure memcache

If you have any questions don't hesitate to write them in comments.

Part 2