News

Tips to Avoid Pitfalls for GUI Translation Using Qt

AndrewMarshall
Senior Software Engineer

Developing an international GUI can be challenging. Here are a few tricks of the trade – before you start, during design and development, and at the end with testing – to make the experience as painless as possible.

5 Tips for Before You Start Developing an International GUI

When you are developing an international GUI, planning ahead can save you time and money. Here are a few tips to get you started.

Put each string into Qt’s translation system so you can access all the strings in Qt Linguist (and not have to hunt them down). For example:
- qsTr(“My text here”) or
- QObject::tr(“My text here”) or
- QCoreApplication::translate(“My text here”)
Use functions that have an additional parameter for disambiguation to help translators. For example:
- qsTr(“Right”, “not left”)
- qsTr(“Right”, “correct”)
Define all your strings in one place and use a variable. For example:
- QString String_NAME = QCoreApplication::translate( “Name:” );
- QLabel* myLabel = new QLabel(this, String_NAME_C);
If you are not using Qt’s translation tools, don’t put your text in the code at all. Make a datafile (XML, csv, your choice) and load the strings from there.
- If the translation company is not familiar with Qt Linguist, you’re going to have to provide the strings in a usable form. Also, if the text is outside the program, you can change it or swap it out without recompiling.
Write words like you normally would, even if you plan on displaying them in all caps. “Name” instead of “NAME”.
- Use the upper function (or QML property font.capitalization) for all caps because not all languages have this concept.
- Also, there are probably places in the code where you don’t want to capitalize but want to use the same string.

5 Tips for Design and Development of an International GUI

There are a number of best practices for designing and programming an international GUI to make translation easier.

Provide double the amount of space for any given text.
- Some languages are notorious for being long compared to English, like German, Russian, and Greek. German also sometimes combines words that are separate in English.
- You may be able to compensate by having enough vertical space to provide a newline. When using multiple lines of text, avoid manual line breaks, if possible, and use automatic word wrapping because different languages may want to wrap at different places.
- Be aware of especially short words that you squeezed in. If text is at the head of a column of widgets, it’s probably a bad idea to set the width of that column to the text’s length.
Choose a flexible font, or be able to change it.
- If you want to use a unique font for your application, make sure it supports more than English letters and that it is unicode compatible. You may need to use a different font to support East Asian languages. Enable the GUI to change fonts based on language.
Consider space for people’s names.
- If your application has to show lists of names, like patient names, make sure you have space to accommodate long names. This is not part of translation, per se, but it comes with the territory. .
Use elements that don’t have to be translated.
- A “close” could be an X. A “back” and “forward” can be arrows.
- This will also save you money, since translators are usually paid by the word. It can also save you space.
- Make sure the symbols you use are intuitive in the countries the GUI will be used.
- There may also be some strings that use letters but don’t have to be translated. For example, there could be latin words or phrases, scientific names, industry specific words, or copyright names that need to stay the same. Call these out because sometimes they get translated by mistake!
Internationalization is not just about translating strings. Make sure to support different date and number formats.
- Commas and decimal points for the thousands separators and radix point are flipped in some countries.
- Month and day are flipped in shorthand formats (MM/DD/YYY vs. DD/MM/YYY). Or always use a format that is understood universally, such as “YYYY-MM-DD”.

5 Tips for Testing an International GUI

Here are some strategies and other tips for testing your translated software when developing an international GUI.

Design your software to handle language changes on-the-fly. The software requirements might limit this, but if possible, be able to change languages without
- Restarting the program
- Recompiling
- Depending on an OS language setting
- The entire deployment or installation process! Your software might ask during installation what language to use, but be able to change it without reinstallation.
Have a dummy translation file.
- It could be useful to have a translation file that is English but puts junk around each string, like “Name” becomes “XXXNameXXX”. Run your program with this translation. If you see some text that does not have the Xs, it’s a rogue string that didn’t get properly put into a qsTr() or whatever system you are using. This is also a way to test if you gave your text enough space.
- Another way to possibly use this system is to set your program to use the junk translation, then switch over to one of the legitimate translations. If you see any of the junk, somehow that word didn’t make it. Either the translator forgot a string or the software isn’t updating all the strings properly.
Use some sort of screen viewer
- Being able to navigate to all screens quickly to spot check the strings, without having to ‘use’ the software, is a very helpful thing to have. It is also nice to have a way to make hidden strings visible. Some strings might only be visible if certain conditions are true, and these are easy to miss in testing.
- A viewer could also be helpful for the translator too, if you’re able to give it to them. They might be unable to run the real software.
Beware of clipping
- If you didn’t give your text enough width, it is easy to see if your word cuts off when you only see half a letter drawn. But there are more insidious cases. Sometimes a translation can add more words and gets cut off in the middle of a space between words, or triggers a word wrap when you assumed it would be one line.
- You could program against these situations by never, ever clipping text. Another technique is to have a ‘border mode’ where you display all your widgets with a 1 pixel border and see if any text spills out of it.
Use a diff tool
- This is where it’s helpful to keep all your strings in one file. Take your English file and diff it against a translated version. Now you can see if something didn’t get translated. Though keep in mind that sometimes a word can be the same in two languages.

Revisions

There will need to be revisions. You can count on it. Despite your best efforts using the tips above, you’ll find issues with the GUI design, rogue strings, and translator mistakes. You and the translator could even make no mistakes and still have to revise. This is because…

New strings could be added while the old batch is being translated
Old strings could change while the old batch is being translated
Some translators could finish before other translators and you have partial integration
Something just didn’t work in translation and you have to rethink the original word or phrase

Things could get very complicated very quickly if you get revisions mixed up in a merge. If possible, do a string freeze, and do things in well defined batches.