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

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