Qt Internationalization

Integrated Computer Solutions Inc. www.ics.com
Qt Internationalization
Localizing with Qt and QML
1
Visit us at http://www.ics.com
Produced by Integrated Computer Solutions
Material based on Qt 5.12
Copyright 2019, Integrated Computers Solutions, Inc.
This work may not be reproduced in whole or in part without the express written consent of Integrated Computer Solutions, Inc.

2
➢ What is Internationalization?
➢ Traditional Qt (C++)
➢ Qt Quick (QML)
➢ Generating and Loading Translations
➢ Qt Linguist
➢ Advanced Topics
➢ Common Errors and Useful Tips
➢ Demo
2

What is Internationalization?
3
● internationalization, i18n:
● localization, l10n :
3
"Localization is the process of adapting software for a specific region or
language by adding locale-specific components and translating text."*
"Internationalization is the process of designing a software application so that
it can be adapted to various languages and regions without engineering
Changes."*
*Source Wikipedia

What is a Localization?
4
Not just the language for UI strings, but also:
● Time and Date
● Currency, Number Formatting, Paper Sizes
● Measurement Units (metric versus imperial)
● Fonts
● Icons, Images, other Multimedia files
● Text encoding format
● Text direction
● Widget appearance (size and layout)
● Cultural differences
4

Costs of a Localization?
5
● Translations can be expensive @ 20¢+/word.
● More Localizations == More chances for QA issues.
● Translation is a skill, people typically don't make good or efficient
translators even if they are fluent in the relevant language.
● Don't underestimate the effort involved in the translation portion of
localization
● Plan! It can be costly and more time consuming to add support later.
● String Freezes give translators time to work, and test.
● Use precise language.
● UX and Localization work together to prevent QA for locales
5

Localization with Qt
6
Qt makes localization painless for developers:
● Unicode throughout
● QtCreator creates Unicode source files by default.
● Provides localization classes
● Layout managers will adjust based on text string lengths
● Qt can handle right-to-left and left-to-right languages.
● Includes Qt Linguist for managing UI strings
○ .ts files are XML and can be edited by hand if desired
○ .qm files are binary and more efficient to load at run time
6

Qt localization workﬂow
7
myapp.cpp
myapp_fr.ts
myapp_ru.ts
myapp_fr.qm
myapp_ru.qm
myapp
Strings extracted
with lupdate
Translators update files
Compiled with lrelease
Loaded with QTranslator.load()
myui.ui
myapp_ru.ts
myapp_fr.ts
7

8
➢ Qt Quick (QML)
➢ Qt Linguist
➢ Advanced Topics
➢ Demo
8

Localization with Qt - UI Strings
9
● Distinguish user-visible localizable strings from non UI strings
● Use QString / QChar, they are Unicode
● Avoid using std::string / char they are not Unicode.
● To Prevent automatic casts between QString and char*.
DEFINES += QT_NO_CAST_TO_ASCII QT_NO_CAST_FROM_ASCII
● Casting to char* or char may be unavoidable when interfacing
with other libraries. You can use the QString conversion
operators: QString::utf8(), QString::toUtf8() etc...
9

Localization with Qt - UI Strings
10
● All literal UI strings are wrapped in localization
functions
● Replaces string with translation at run-time based on
locale
● Usually use tr() function
● Example: QPushButton *b = new QPushButton(tr("Save"));
10

Localization with Qt - QObject::tr()
11
● Returns a translated version of the source text by searching
the loaded qm files.
● Flag the string for inclusion in generated ts files.
● Uses the owning QObject as its context.
● QCoreApplication::translate() is similar to tr() but requires a
context to be set.
What does it do?
11

12
● Can use structured comments to annotate a string with
information for translators
● This works in both C++ and QML
//: This refers to a network address.
addressLabel->setText(tr("Address:"));
/*: This refers to the age of a network packet. */
QString packetAge = tr("Age");
//= freeLibre
//: free as in freedom
QString fileText = tr("Free");
//= freeBeer
//: free as in beer
QString fileText = tr("Free");
12

13
● Optional second argument can be used to disambiguate
identical strings that have different meanings in different
contexts
● For example:
○ tr("free", "as in beer")
○ tr("free", "as in freedom")
● Above are handled as two distinct strings to translate (in
French the first might be translated as "gratuit" and the second
"libre")
● Optional third argument used to handle plurals (example later)
13

Localization with Qt - Examples
14
BAD, string cannot be localized
QString s = "Hello, world!";
GOOD
QString s = tr("Hello, world!");
14

15
int i = 58; int j = 5000;
Good, However order may be incorrect for some languages
tr("Copying File ") + i + tr(" of ") + j;
Better, The Whole phrase is provided to translator
tr("Copying File %1 of %2").arg(i).arg(j);
Best, The “L” modifier inserts a localized number
tr("Copying File %L1 of %L2").arg(i).arg(j);
Output(en_US): “Copying File 58 of 5,000”
Output(en_CA): “Copying File 58 of 5 000”
15

16
int n = messages.count();
Bad, rules for plural forms are different in some languages
if (n == 1)
msg = tr("You have 1 new message.");
else
msg = tr("You have %1 new messages.").arg(n);
Good
msg = tr("You have %n new message(s).", nullptr, n);
16

1717

Localization with Qt - Keyboard Accelerators
18
● Keyboard Accelerators can be Localized
● QKeySequence contains common ones.
● Choice of accelerator keys in other languages are left to the
translator
● E.g. CTRL+Q may not exist on Japanese or Chinese user's
keyboard
quitAction = new QAction(tr("&Quit"), this);
quitAction->setShortcut(tr("Ctrl+Q"));
quitAction->setShortcut(QKeySequence::Quit);
18

Localization with Qt - Static Strings
19
● Need to handle literal strings differently when they are outside of a class, such
as constant strings
● The macro QT_TR_NOOP marks the strings as needing translation so they
will be extracted by lupdate and put in .ts file
● The macro QT_TRANSLATE_NOOP takes a string and a context, typically a
classname, which can be used when calling QCoreApplication::translate().
They need to match to translate
● The macros return the source string, so you still need to call tr() when using
the string in order to translate it
● Non Qt classes can use the Q_DECLARE_TR_FUNCTIONS(classname)
macro to enable tr calls.
19

Localization with Qt - Static Strings
20
Example:
static const char *baseNames = {
QT_TR_NOOP("adenine"),
QT_TR_NOOP("cytosine"),
QT_TR_NOOP("guanine"),
QT_TR_NOOP("thymine")
};
QString base(int num) {
return tr(baseNames[num]);
}
20

21
➢ Qt Quick (QML)
➢ Qt Linguist
➢ Advanced Topics
➢ Demo
21

Localization with Qt Quick (QML)
22
● Wrap all strings in qsTr() function
● Like tr(), supports "%n" replacement and .arg()
○ e.g. qsTr("You are %1 years old.").arg(age())
● Doesn't accept multiple arguments but can use .arg() multiple
times:
● qsTr() can also be used in JavaScript code
var dateHeader =
qsTr("Downloading file %1 of %2").arg(fileNumber()).arg(totalNumberOfFiles())
22

23
• Can test a translation with qmlviewer or qmlscene using the -translation option,
e.g.
qmlviewer -translation myapp.qm myapp.qml
• See the Internationalization and Localization with Qt Quick section in the Qt
documentation
• In addition to qsTr(), QML also supports
○ qsTranslate()
○ qsTrid()
○ QT_TR_NOOP()
○ QT_TRANSLATE_NOOP()
○ QT_TRID_NOOP()
23

24
C++ Function QML/JavaScript Function
tr() qsTr()
translate() qsTranslate()
qtTrId() qsTrId()
QT_TR_NOOP() QT_TR_NOOP()
QT_TRANSLATE_NOOP() QT_TRANSLATE_NOOP()
QT_TRID_NOOP() QT_TRID_NOOP()
24

25
➢ Qt Quick (QML)
➢ Qt Linguist
➢ Advanced Topics
➢ Demo
25

Localization With Qt: Generating Ts Files QMAKE
26
• List the .ts files in your Qt project file .pro using
TRANSLATIONS variable, e.g.
TRANSLATIONS += myapp_de.ts myapp_fr.ts myapp_it.ts
• Run lupdate to extract/merge strings when UI strings change.
system (lupdate myapp.pro)
$ lupdate myapp.pro
$ lupdate main.cpp main.qml myapp_ru.ts
• lrelease is used to compile .ts files to .qm files
system (lrelease-pro myapp.pro)
$ lrelease-pro myapp.pro
$ lrelease myapp_ru.ts
26

Localization With Qt: Generating Ts Files CMAKE
27
find_package(Qt5LinguistTools)
set(needsTranslation
Mainwindow.cpp
… More source files
)
set(languageFiles
myApp_en.ts
myApp_fr.ts
myApp_de.ts
)
qt5_create_translation(TSFiles
needsTranslation
languageFiles
)
add_custom_target(TRS ALL DEPENDS ${TSFiles})
Qt5LinguistTools Notes:
● CMake 3.1.0 +
● Provides two macros
qt5_create_translation
qt5_add_translation
find_package(Qt5LinguistTools)
qt5_add_translation(QMFiles
mainwindow.cpp
myApp_en.ts myApp_fr.ts myApp_dr.ts
)
add_custom_target(QMS ALL DEPENDS ${QMFiles})
27

Localization With Qt: Loading Translations - Runtime
28
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QTranslator qtTranslator;
qtTranslator.load(QString("qtCore_%1")
.arg(QLocale::system().name(),
QLibraryInfo::location(QLibraryInfo::TranslationsPath));
);
app.installTranslator(&qtTranslator);
QTranslator myappTranslator;
myappTranslator.load("myapp_" + QLocale::system().name());
app.installTranslator(&myappTranslator);
...
return app.exec();
}
28

Localization With Qt: Deploying Translations
29
You can store .qm files in resources.
Advantages:
● Fewer files to distribute with your application
● Always easy to load files with a resource path
Disadvantages:
● Cannot change or add new translations without rebuilding application
● Cannot distribute translations separately from application
You can distribute .qm files as external files.
Advantages:
● Can distribute without the application
● Can add new translations without rebuilding the application
Disadvantages:
● More files to distribute with your application
● Need to get on disk path to load at runtime
29

30
➢ Qt Quick (QML)
➢ Qt Linguist
➢ Advanced Topics
➢ Demo
30

Qt Linguist:
31
● Cross Platform GUI Application for working with Qt Translations.
● Translators can get standalone copies of Qt Linguist.
31

Qt Linguist: Phrase Books
32
● Phrase books Contain Common Phrases used in a language.
● Used as a tool to help speed up translation.
● Provides a translation that Qt Linguist can then suggest when those
phrases are used in your application.
32

33
➢ Qt Quick (QML)
➢ Qt Linguist
➢ Advanced Topics
➢ Demo
33

Localization Advanced: Localizers use placeholders
34
● Placeholders:
○ Arg Placeholders:
■ Format: %[L]<number> ex: %1 %L1
■ Can have multiple in a string, always start with %1
■ String order doesn’t matter. “%2, %1” and “%1, %2”
○ Translation function provided
■ Format: %[L]n ex: %n %Ln
■ %n is a number, used with plurals.
○ Optional L Modifier will localize inserted number.
● Accelerators
○ Format: &<character> ex: “e&dit”
○ Localizers are responsible for them.
○ Character that follows the & becomes the accelerated key.
34

Localization Advanced: Multimedia Files
35
● Use the QResource system, resource prefixes have a
language tag
● Matching prefixes / alias will be replaced based on
language tag
● The best practice is to make your multimedia resources
universal
Image, video, sound files
35

Localization Advanced: Cultural Differences
36
● Symbols used in images and icons may not be universal to all
cultures (e.g. Red Cross, check mark)
● Colors may not have the same meaning (e.g. red may not
signify danger). Use the Palette to get your colors.
● Some images may be offensive to some cultures (e.g. animals)
● Embedded Fonts may be missing characters
36

Localization Advanced: Text Codecs
37
● One day hopefully everything will use Unicode.
● File contents may not be encoded in Unicode or 8-bit characters
● May need to use appropriate text codec for locale
● Qt provides most common ones in QTextCodec
● Default text codec is set based on locale
● You may need to set a different text codec (or have the user
select from the UI)
● Note: your source code should be encoded in Unicode.
37

Localization Advanced: Input Methods
38
● Some languages require input method editor (IME)
● E.g. Chinese has thousands of characters, one to one mapping
of keyboard keys to characters is not possible
● Usually transparent to developer, Qt through standard input
widgets interfaces with input method editors such as Scim when
present
● Typically set up at OS or desktop level
● Just make sure you don't use custom made input widgets
38

Localization Advanced: Id Based Translations
39
● Strings can be translated by id with qrTsId(“ID”) and qsTrId(“ID”)
● Static Strings are marked with QT_TRID_NOOP(“ID”)
● Id based strings do not get a context.
● Use //% comments for parameters //% “Message Count: %1”
● Good for strings that come from outside your code.
● Must use -idbased option for lrelease when generating .qm files
● It is not recommended to mix ID based and Context based
translations in one application, Mixing them can result in
incomplete translations being generated.
39

Localization Advanced: Dynamic Language Changes
40
● May want to change language at run time, e.g. from user input
rather from locale
● Requires some extra effort to handle LanguageChange event to
update text
● See "Dynamic Translation" section in Qt documentation
"Internationalization with Qt"
● See section "Dynamic Language Switching" in Blanchette and
Summerfield’ book “C++ GUI Programming with Qt4”
40

Localization Advanced: Other l10n Methods
41
● You don't have to use Qt localization support
● There are other localization libraries and tools, e.g. GNU gettext
and .po files
● KDE uses their own scheme based on gettext
● Essentially just use different wrapper functions for strings
● For uic generated code, you can change the function used for
translating strings with -tr option
● lconvert tool can convert files between .ts, .po, and .xlf formats
41

Localization Advanced: lconvert
42
The lconvert tool works with common l10n file types
● Supports the following formats
○ Qts Own formats: Qt Message File (*.qm), Translation Source (*.ts), Qt Phrasebook (*.qph)
○ GNU Gettext formats: Templates (*.pot), GNU Gettext files (*.po)
○ XLIFF Files (*.xlf)
● Concatenate files
○ lconvert - o DESTDIR/myapp_ru.qm qtbase_ru.qm myapp_ru.qm
● Convert Between formats
○ lconvert -of qph -o myapp_fr.qph myapp_fr.ts
● Other options to sort, remove, change language, prune ui file strings , etc…
42

43
➢ Qt Quick (QML)
➢ Advanced Topics
➢ Demo
43

Localization With Qt: Common Errors and Problems
44
● Concatenating strings
● Forgetting to localize dates, currency, etc.
● Forgetting to add translator comments for non-obvious strings,
e.g. "%1/%2"
● Not using disambiguation when using the same string for
different roles
● Using tr() on strings that change at run-time
● If directly editing ts files, watch encoding format used by your
editor. Can also be an issue with source files.
● Not Using Locale Aware compare methods when needed.
44

Localization With Qt: Useful Tips
45
● Generate dummy translations for test purposes (i.e. all
uppercase, additional Length)
○ Can be done with, e.g. a Perl script
○ Google Language Tools (don't expect quality)
● ts files can be edited by hand or scripts as they are XML
● Always, Always Use Layouts.
● QLocale stable but continues to improve
45

Localization With Qt: Summary
46
Qt makes it easy to localize your application
With a few simple steps:
● Use QString for all user-visible text
● Use tr() or qsTr() for all user-visible literal text
● Use layout managers in dialogs
● Extract strings using lupdate and produce .ts files for each
language
● Load translation files at run-time
46

47
➢ Qt Quick (QML)
➢ Advanced Topics
➢ Demo
47

Integrated Computer Solutions Inc. www.ics.com 4848

Integrated Computer Solutions Inc. www.ics.comIntegrated Computer Solutions Inc.
Thank You for attending!
Any Questions?
49
webinars@ics.com

Qt Internationalization

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Qt Internationalization

Similar to Qt Internationalization (20)

More from ICS

More from ICS (20)

Recently uploaded

Recently uploaded (20)

Qt Internationalization