1/*
2 SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef KLOCALIZEDTRANSLATOR_H
7#define KLOCALIZEDTRANSLATOR_H
8
9#include <ki18n_export.h>
10
11#include <QTranslator>
12
13#include <memory>
14
15class KLocalizedTranslatorPrivate;
16
17/**
18 * @class KLocalizedTranslator klocalizedtranslator.h <KLocalizedTranslator>
19 *
20 * @brief A QTranslator using KLocalizedString for translations.
21 *
22 * This class allows to translate strings in Qt's translation system with KLocalizedString.
23 * An example is the translation of a dynamically loaded user interface through QUILoader.
24 *
25 * To use this Translator install it in the QCoreApplication and provide the translation domain
26 * to be used. The Translator can operate for multiple contexts, those needs to be specified.
27 *
28 * Example for translating a UI loaded through QUILoader:
29 * @code
30 * // create translator and install in QCoreApplication
31 * KLocalizedTranslator *translator = new KLocalizedTranslator(this);
32 * QCoreApplication::instance()->installTranslator(translator);
33 * translator->setTranslationDomain(QStringLiteral("MyAppsDomain"));
34 *
35 * // create the QUILoader
36 * QUiLoader *loader = new QUiLoader(this);
37 * loader->setLanguageChangeEnabled(true);
38 *
39 * // load the UI
40 * QFile uiFile(QStringLiteral("/path/to/userInterface.ui"));
41 * uiFile.open(QFile::ReadOnly);
42 * QWidget *loadedWidget = loader->load(&uiFile, this);
43 * uiFile.close();
44 *
45 * // the object name of the loaded UI is the context in this case
46 * translator->addContextToMonitor(loadedWidget->objectName());
47 *
48 * // send a LanguageChange event, this will re-translate using our translator
49 * QEvent le(QEvent::LanguageChange);
50 * QCoreApplication::sendEvent(loadedWidget, &le);
51 * @endcode
52 *
53 * @since 5.0
54 **/
55class KI18N_EXPORT KLocalizedTranslator : public QTranslator
56{
57 Q_OBJECT
58public:
59 explicit KLocalizedTranslator(QObject *parent = nullptr);
60 virtual ~KLocalizedTranslator();
61 QString translate(const char *context, const char *sourceText, const char *disambiguation = nullptr, int n = -1) const override;
62
63 /**
64 * Sets the @p translationDomain to be used.
65 *
66 * The translation domain is required. Without the translation domain any invocation of
67 * translate() will be delegated to the base class.
68 *
69 * @param translationDomain The translation domain to be used.
70 **/
71 void setTranslationDomain(const QString &translationDomain);
72
73 /**
74 * Adds a @p context for which this Translator should be active.
75 *
76 * The Translator only translates texts with a context matching one of the monitored contexts.
77 * If the context is not monitored, the translate() method delegates to the base class.
78 *
79 * @param context The context for which the Translator should be active
80 *
81 * @see removeContextToMonitor
82 **/
83 void addContextToMonitor(const QString &context);
84
85 /**
86 * Stop translating for the given @p context.
87 *
88 * @param context The context for which the Translator should no longer be active
89 *
90 * @see addContextToMonitor
91 **/
92 void removeContextToMonitor(const QString &context);
93
94private:
95 std::unique_ptr<KLocalizedTranslatorPrivate> const d;
96};
97
98#endif // KLOCALIZEDTRANSLATOR_H
99

source code of ki18n/src/i18n/klocalizedtranslator.h