Translating Qwitter

By Cleverson Casarin Uliana, Jan 13 2010

Note: to fill in edit fields, save files, and create folders as explained later, you must keep the letters cases as they appear in this tutorial.

Running from sources

To translate Qwitter, first you must be able to run it from sources successfully. This involves installing a Mercurial client, cloning the source code from the repository, installing all of its required dependencies, and running it. You also need an SVN client such as TortoiseSVN to commit your translation, as committing straight to the Mercurial repository causes your changes to be lost.

Learning Mercurial and SVN is a bit beyond the scope of this document. To sumarize it, you have to open a command prompt, then create an empty directory, that's where you will place the Qwitter source code. For this tutorial, I will assume it to be C:\qwitter. Next, switch to that directory and issue the following command: hg clone  http://hg.qwitter-client.net/qwitter

In the future, whenever you need to just update your sources copy, you may just issue this command instead: hg pull -u

Next, you may use Windows Explorer to go to c:\qwitter\dependencies. You must install everything in this folder, and then you can run and use Qwitter normally by going to qwitter\src and running the file qwitter.pyw.

There is a subversion mirror for some qwitter subdirectories like documentation and locale, available at  http://svn.qwitter-client.net/QwitterTranslations

You must use the SVN client to commit your translations updates, otherwise they will be overwritten. Nonetheless, you must retrieve the entire Qwitter source code from the Mercurial repository, otherwise you will not be able to update your strings catalog using PoEdit? (see instructions below).

Translating

Possible translation methods

There are at least two methods you may use to translate Qwitter. One is to use some dedicated command line tools found in the qwitter/tools folder to generate the file containing the strings to be translated, then use any text editor to translate them, and finally use another command to compile the finished translation.

PoEdit?: The better way

But here I'm going to explain another method, more secure and productive in my opinion. It involves using PoEdit?, a program with a nice GUI to hold all of the original and translated strings. PoEdit?'s homepage is:  http://www.poedit.net/

Installing and running PoEdit?

You can always download the latest Windows PoEdit? version at:  http://sourceforge.net/projects/poedit/files/

Install it by following the on-screen instructions. Except for the second screen, where you must check the "I agree" option, I suggest to accept all of the default options, especially in the components screen, where you must perform a full installation.

When you run PoEdit? for the first time, the first screen is for you to choose the default language for the program's menus, windows and options. It probably will default to your system language. In this tutorial, I'm going to refer to PoEdit?'s menus and options by their English names.

The next step is to enter your name and e-mail for PoEdit? to fill in the headers of the strings catalog files properly. Enter them at the respective field in the window dialog that appears. Next, press control+tab until you reach the "parsers" tab, then find the list of languages and select Python. Tab to the edit button and hit space bar, then tab to the "list of extensions" field and append a semicolon followed by "*.pyw" to it. The field must look like this:

*.py;*.pyw

Next, find and press OK to close the Python parser window, then press OK to close the prefferences window, since all other options may be left as default.

creating the Qwitter Translation Catalog

Go to the file menu and click on "New catalog...". Here you must enter some more info for this specific project. Almost all of the fields are optional, but entering correct information is always desirable.

In "Project name and version" you may put "Qwitter " followed by the highest version found in the file qwitter\docs\changelog.txt. It might be for example:

Qwitter 7.00

In "team" you might put something like "<your language code> language team" or simply your name if you are the only translator. In "team's e-mail address" put your e-mail. Next, select in the combo boxes the language and country for your project. In the charset and source code charset combo boxes, select "utf-8", as Qwitter is written in Unicode.

Next, press control+tab to go to the path tab, then enter in the base path edit field the absolute path of the folder where you downloaded the Qwitter's sources to, e.g. "c:\qwitter". Tab to and press the button that follows, then enter "src" in the edit field and press enter. This is the path from where PoEdit? will scan the source code for translatable strings. Tab to OK and press it.

A "Save as" standard dialog will appear. Type "qwitter.po" in the file name field, then choose the folder "qwitter\src\locale\<languageCode>\LC_MESSAGES", where <languageCode> is actually the code of the language to which you are translating Qwitter, in the ISO-639 format. If such folder structure does not exist, create it.

PoEdit? will then save two files in that folder. "qwitter.po" holds all the original and translated strings in text format. You may check it using any text editor whenever you want or need it. "qwitter.mo" is the binary version of qwitter.po; it's the file Qwitter actually reads and assumes at its runtime. Technically, For Qwitter to run in your language, you must only distribute qwitter.mo, however we ask that you provide both files to foster rapid translation and easy modification of languages.

Just as an info, If you were going to use the pygettext command line tool instead of PoEdit?, there would be another file called qwitter.pot, which would hold all original strings, then you would save it as qwitter.po after translating. PoEdit? needs not to generate a pot file, as it can scan the source code and update the PO catalog automatically.

You will now be presented with an empty list and a blank edit field, between which you can switch using tab. Go to the catalog menu and enter "update from source". This option instructs PoEdit? to scan the entire Qwitter source code for translatable strings. You must run it everytime you want to check whether there are new untranslatable strings to be added or obsolete strings to be removed from your project, no matter if it is or is not the first time you translate it.

After scanning the code, it may happen to appear a window giving some errors related to incorrectly terminated strings. You may simply ignore it and press OK, as they are just warnings without relevance. Next, PoEdit? will present the list of new strings that are to be added to your catalog file, and the obsolete strings, that is, strings that are not part of the program anymore, most likely because some option had its name changed or had been replaced with one or more similar options. If it's the first time you scan the sources for strings, the new strings list will probably contain hundreds of strings. You need not to walk through all the list; simply hit OK.

Translating

You have now landed on the same list as before, but now fulfilled with all of Qwitter's strings to be translated. Read the status bar to see how many strings are translated already, how many are not, and how many are fuzzy. A fuzzy string is one that PoEdit? has tried to automatically guess the translation, thus it may be wrong. To insert or correct the translation for a string, first select it with the arrows, then tab to the blank edit field and type its translation.

You may want to spell the original string to be aware of any punctuation mark, capital letters, etc. PoEdit? has a keystroke you may press while on an original string, alt+C, that copies the original string to the edit field when pressed. You may then replace it with your translation normally.

Press control+s at any moment to save your work. Each time you press this key, PoEdit? saves qwitter.po and also re-compiles qwitter.mo with the latest strings you translated and just saved. When finished translating, you may go to the qwitter\locale\<languageCode>\LC_MESSAGES folder, and commit qwitter.mo and qwitter.po to either the Mercurial or the QwitterTranslations? subversion repository. In the later case, note that you must svn add both the new language folder under locale and both of these files when committing.