Translating AntiMicro

Introduction

antimicro doesn't use the normal way of organizing Qt projects. Particularly, there is no .pro file. We need to manually extract the strings, translate them, and compile them for testing.

Below is an overview of the translation process:

1. In the .cpp source files, there are many strings, especially for the UI part. We want to translate them so that people can understand them easily. According to Qt, we need to use the tr() function to mark the strings out. This is done by developers so that translators don't need to worry about this.

2. We have so many source files, so the strings are scattered around. We want to have a central place for them so that we can translate them consistently. To do this, we use the lupdate command to extract the strings marked with tr() out of the source files, and put them into a single .ts file for each language. At this time, we want to keep the obsolete strings so that we can copy and paste them during translation.

3. Now we have a central place for the strings. We can use Qt Linguist to translate them. Qt Linguist has nice features such as suggestions and phrase book to make the translation more consistent. Upon saving the .ts file, Qt Linguist will write the translated strings back to the .ts file, as well as some metadata.

4. Now we have a problem. The translated .ts file is still in the human-readable text form, and antimicro's binary executable does not like it. We need to use the lrelease command to "compile" the translated strings into a format that is recognizable by the application. The result is a .qm file. We can test this file with the binary executable.

5. After several rounds of translating in Qt Linguist, saving the .ts file, using lrelease to update the .qm file, and testing, we may be satisfied with the translation. At this time, we want to get rid of those obsolete strings to make the .ts file clean.

6. Finally, it's time to commit the translation changes. We only need to commit the .ts file since the .qm file will be generated automatically during antimicro's installation.

Preparation

As translators, we need to install Qt Linguist. It contains a GUI application for translation, as well as some command-line tools such as lupdate and lrelease. On Arch Linux, I can install it through the qt5-tools package. You might need to look for similar packages or the official Qt installer on your distribution or platform. Both Qt 4 and Qt 5 should work with antimicro.

Workflow

Take Simplified Chinese translation (zh_CN) on Linux as an example. Choose the language file according to your language. Please let us know if you want to add a new language.

Suppose that we are under the project root folder at the beginning of each step.

1. Build antimicro first. Skip this step if you have already done this:

   mkdir build
   cd build
   cmake ..
   make
   cd ..
   

2. Update the .ts file, but keep the obsolete strings:

   lupdate src/ -ts share/antimicro/translations/antimicro_zh_CN.ts
   

3. Open the .ts file in the previous step with Qt Linguist. Translate the strings. The references section below has some information on how to use Qt Linguist. Save the .ts file when finished.

4. "Compile" the .ts file:

   lrelease share/antimicro/translations/antimicro_zh_CN.ts -qm build/share/antimicro/translation/antimicro_zh_CN.qm
   

5. Test the translation with the binary executable:

   build/bin/antimicro
   

6. Repeat Step 3 to 5 until you are satisfied with the translation.

7. Update the .ts file again to get rid of the obsolete strings:

   lupdate src/ -ts share/antimicro/translations/antimicro_zh_CN.ts -no-obsolete
   

8. Commit the changes in the .ts file. Make a pull request.

9. You might want to reinstall antimicro so that your installed version has the latest translation. Or you can put the generated .qm file to your local installation folder. Mine is at /usr/local/share/antimicro/translations/antimicro_zh_CN.qm.

References

Qt Linguist Manual