1/*
2 SPDX-FileCopyrightText: 2011 Marco Martin <mart@kde.org>
3 SPDX-FileCopyrightText: 2015 Aleix Pol Gonzalez <aleixpol@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KLOCALIZEDQMLCONTEXT_H
9#define KLOCALIZEDQMLCONTEXT_H
10
11#include <ki18nqml_export.h>
12
13#include <QObject>
14#include <QVariant>
15#include <memory>
16
17class QQmlEngine;
18
19class KLocalizedQmlContextPrivate;
20
21/*!
22 * \class KLocalizedQmlContext
23 * \inmodule KI18nQml
24 *
25 * \brief This class is meant to be used to simplify integration of the KI18n framework
26 * in QML.
27 *
28 * The way to do so, is by creating this object and setting it as a context
29 * object:
30 *
31 * \code
32 * QQmlApplicationEngine engine;
33 * auto ctx = new KLocalizedQmlContext(&engine);
34 * engine->rootContext()->setContextObject(ctx);
35 * QQmlEngine::setContextForObject(ctx, engine.rootContext());
36 * ctx->setTranslationDomain(...);
37 * \endcode
38 *
39 * In many cases this can be simplified using KLocalization::setupLocalizedContext():
40 * \code
41 * QQmlApplicationEngine engine;
42 * KLocalization::setupLocalizedContext(&engine);
43 * \endcode
44 *
45 * Then i18n*() and xi18n*() functions should be available for use from the code
46 * loaded in the engine, for the view.
47 *
48 * Unlike its predecessor KLocalizedContext this does automatically trigger
49 * a binding re-evaluation when the application language is changed at runtime
50 * (with Qt 6.6 or higher).
51 *
52 * \note Plural functions differ from the C/C++ version. On QML/JS we can get a
53 * real value easily. To solve warnings on those cases we'll cast the first argument
54 * to make sure it's taken into account for the plural.
55 *
56 * \since 6.8
57 */
58class KI18NQML_EXPORT KLocalizedQmlContext : public QObject
59{
60 Q_OBJECT
61
62 /*!
63 * \property KLocalizedQmlContext::translationDomain
64 *
65 * This property only needs to be specified if the context is being run on a library.
66 * in an application there is no need to set the translation domain as the application's
67 * domain can be used.
68 */
69 Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain NOTIFY translationDomainChanged)
70
71public:
72 /*!
73 *
74 */
75 explicit KLocalizedQmlContext(QObject *parent = nullptr);
76 ~KLocalizedQmlContext() override;
77
78 /*!
79 *
80 */
81 QString translationDomain() const;
82
83 /*!
84 *
85 */
86 void setTranslationDomain(const QString &domain);
87
88 Q_INVOKABLE QString i18n(const QString &message,
89 const QVariant &param1 = QVariant(),
90 const QVariant &param2 = QVariant(),
91 const QVariant &param3 = QVariant(),
92 const QVariant &param4 = QVariant(),
93 const QVariant &param5 = QVariant(),
94 const QVariant &param6 = QVariant(),
95 const QVariant &param7 = QVariant(),
96 const QVariant &param8 = QVariant(),
97 const QVariant &param9 = QVariant(),
98 const QVariant &param10 = QVariant()) const;
99
100 Q_INVOKABLE QString i18nc(const QString &context,
101 const QString &message,
102 const QVariant &param1 = QVariant(),
103 const QVariant &param2 = QVariant(),
104 const QVariant &param3 = QVariant(),
105 const QVariant &param4 = QVariant(),
106 const QVariant &param5 = QVariant(),
107 const QVariant &param6 = QVariant(),
108 const QVariant &param7 = QVariant(),
109 const QVariant &param8 = QVariant(),
110 const QVariant &param9 = QVariant(),
111 const QVariant &param10 = QVariant()) const;
112
113 Q_INVOKABLE QString i18np(const QString &singular,
114 const QString &plural,
115 const QVariant &param1 = QVariant(),
116 const QVariant &param2 = QVariant(),
117 const QVariant &param3 = QVariant(),
118 const QVariant &param4 = QVariant(),
119 const QVariant &param5 = QVariant(),
120 const QVariant &param6 = QVariant(),
121 const QVariant &param7 = QVariant(),
122 const QVariant &param8 = QVariant(),
123 const QVariant &param9 = QVariant(),
124 const QVariant &param10 = QVariant()) const;
125
126 Q_INVOKABLE QString i18ncp(const QString &context,
127 const QString &singular,
128 const QString &plural,
129 const QVariant &param1 = QVariant(),
130 const QVariant &param2 = QVariant(),
131 const QVariant &param3 = QVariant(),
132 const QVariant &param4 = QVariant(),
133 const QVariant &param5 = QVariant(),
134 const QVariant &param6 = QVariant(),
135 const QVariant &param7 = QVariant(),
136 const QVariant &param8 = QVariant(),
137 const QVariant &param9 = QVariant(),
138 const QVariant &param10 = QVariant()) const;
139
140 Q_INVOKABLE QString i18nd(const QString &domain,
141 const QString &message,
142 const QVariant &param1 = QVariant(),
143 const QVariant &param2 = QVariant(),
144 const QVariant &param3 = QVariant(),
145 const QVariant &param4 = QVariant(),
146 const QVariant &param5 = QVariant(),
147 const QVariant &param6 = QVariant(),
148 const QVariant &param7 = QVariant(),
149 const QVariant &param8 = QVariant(),
150 const QVariant &param9 = QVariant(),
151 const QVariant &param10 = QVariant()) const;
152
153 Q_INVOKABLE QString i18ndc(const QString &domain,
154 const QString &context,
155 const QString &message,
156 const QVariant &param1 = QVariant(),
157 const QVariant &param2 = QVariant(),
158 const QVariant &param3 = QVariant(),
159 const QVariant &param4 = QVariant(),
160 const QVariant &param5 = QVariant(),
161 const QVariant &param6 = QVariant(),
162 const QVariant &param7 = QVariant(),
163 const QVariant &param8 = QVariant(),
164 const QVariant &param9 = QVariant(),
165 const QVariant &param10 = QVariant()) const;
166
167 Q_INVOKABLE QString i18ndp(const QString &domain,
168 const QString &singular,
169 const QString &plural,
170 const QVariant &param1 = QVariant(),
171 const QVariant &param2 = QVariant(),
172 const QVariant &param3 = QVariant(),
173 const QVariant &param4 = QVariant(),
174 const QVariant &param5 = QVariant(),
175 const QVariant &param6 = QVariant(),
176 const QVariant &param7 = QVariant(),
177 const QVariant &param8 = QVariant(),
178 const QVariant &param9 = QVariant(),
179 const QVariant &param10 = QVariant()) const;
180
181 Q_INVOKABLE QString i18ndcp(const QString &domain,
182 const QString &context,
183 const QString &singular,
184 const QString &plural,
185 const QVariant &param1 = QVariant(),
186 const QVariant &param2 = QVariant(),
187 const QVariant &param3 = QVariant(),
188 const QVariant &param4 = QVariant(),
189 const QVariant &param5 = QVariant(),
190 const QVariant &param6 = QVariant(),
191 const QVariant &param7 = QVariant(),
192 const QVariant &param8 = QVariant(),
193 const QVariant &param9 = QVariant(),
194 const QVariant &param10 = QVariant()) const;
195
196 Q_INVOKABLE QString xi18n(const QString &message,
197 const QVariant &param1 = QVariant(),
198 const QVariant &param2 = QVariant(),
199 const QVariant &param3 = QVariant(),
200 const QVariant &param4 = QVariant(),
201 const QVariant &param5 = QVariant(),
202 const QVariant &param6 = QVariant(),
203 const QVariant &param7 = QVariant(),
204 const QVariant &param8 = QVariant(),
205 const QVariant &param9 = QVariant(),
206 const QVariant &param10 = QVariant()) const;
207
208 Q_INVOKABLE QString xi18nc(const QString &context,
209 const QString &message,
210 const QVariant &param1 = QVariant(),
211 const QVariant &param2 = QVariant(),
212 const QVariant &param3 = QVariant(),
213 const QVariant &param4 = QVariant(),
214 const QVariant &param5 = QVariant(),
215 const QVariant &param6 = QVariant(),
216 const QVariant &param7 = QVariant(),
217 const QVariant &param8 = QVariant(),
218 const QVariant &param9 = QVariant(),
219 const QVariant &param10 = QVariant()) const;
220
221 Q_INVOKABLE QString xi18np(const QString &singular,
222 const QString &plural,
223 const QVariant &param1 = QVariant(),
224 const QVariant &param2 = QVariant(),
225 const QVariant &param3 = QVariant(),
226 const QVariant &param4 = QVariant(),
227 const QVariant &param5 = QVariant(),
228 const QVariant &param6 = QVariant(),
229 const QVariant &param7 = QVariant(),
230 const QVariant &param8 = QVariant(),
231 const QVariant &param9 = QVariant(),
232 const QVariant &param10 = QVariant()) const;
233
234 Q_INVOKABLE QString xi18ncp(const QString &context,
235 const QString &singular,
236 const QString &plural,
237 const QVariant &param1 = QVariant(),
238 const QVariant &param2 = QVariant(),
239 const QVariant &param3 = QVariant(),
240 const QVariant &param4 = QVariant(),
241 const QVariant &param5 = QVariant(),
242 const QVariant &param6 = QVariant(),
243 const QVariant &param7 = QVariant(),
244 const QVariant &param8 = QVariant(),
245 const QVariant &param9 = QVariant(),
246 const QVariant &param10 = QVariant()) const;
247
248 Q_INVOKABLE QString xi18nd(const QString &domain,
249 const QString &message,
250 const QVariant &param1 = QVariant(),
251 const QVariant &param2 = QVariant(),
252 const QVariant &param3 = QVariant(),
253 const QVariant &param4 = QVariant(),
254 const QVariant &param5 = QVariant(),
255 const QVariant &param6 = QVariant(),
256 const QVariant &param7 = QVariant(),
257 const QVariant &param8 = QVariant(),
258 const QVariant &param9 = QVariant(),
259 const QVariant &param10 = QVariant()) const;
260
261 Q_INVOKABLE QString xi18ndc(const QString &domain,
262 const QString &context,
263 const QString &message,
264 const QVariant &param1 = QVariant(),
265 const QVariant &param2 = QVariant(),
266 const QVariant &param3 = QVariant(),
267 const QVariant &param4 = QVariant(),
268 const QVariant &param5 = QVariant(),
269 const QVariant &param6 = QVariant(),
270 const QVariant &param7 = QVariant(),
271 const QVariant &param8 = QVariant(),
272 const QVariant &param9 = QVariant(),
273 const QVariant &param10 = QVariant()) const;
274
275 Q_INVOKABLE QString xi18ndp(const QString &domain,
276 const QString &singular,
277 const QString &plural,
278 const QVariant &param1 = QVariant(),
279 const QVariant &param2 = QVariant(),
280 const QVariant &param3 = QVariant(),
281 const QVariant &param4 = QVariant(),
282 const QVariant &param5 = QVariant(),
283 const QVariant &param6 = QVariant(),
284 const QVariant &param7 = QVariant(),
285 const QVariant &param8 = QVariant(),
286 const QVariant &param9 = QVariant(),
287 const QVariant &param10 = QVariant()) const;
288
289 Q_INVOKABLE QString xi18ndcp(const QString &domain,
290 const QString &context,
291 const QString &singular,
292 const QString &plural,
293 const QVariant &param1 = QVariant(),
294 const QVariant &param2 = QVariant(),
295 const QVariant &param3 = QVariant(),
296 const QVariant &param4 = QVariant(),
297 const QVariant &param5 = QVariant(),
298 const QVariant &param6 = QVariant(),
299 const QVariant &param7 = QVariant(),
300 const QVariant &param8 = QVariant(),
301 const QVariant &param9 = QVariant(),
302 const QVariant &param10 = QVariant()) const;
303
304Q_SIGNALS:
305 void translationDomainChanged(const QString &translationDomain);
306
307private:
308 bool eventFilter(QObject *watched, QEvent *event) override;
309 std::unique_ptr<KLocalizedQmlContextPrivate> const d;
310};
311
312/*!
313 * \namespace KLocalization
314 * \inmodule KI18nQml
315 * \brief Namespace containing helpers for localization.
316 */
317namespace KLocalization
318{
319namespace Internal
320{
321[[nodiscard]] KI18NQML_EXPORT KLocalizedQmlContext *createLocalizedContext(QQmlEngine *engine);
322}
323
324/*!
325 * Creates a KLocalizedQmlContext engine and sets it up in the
326 * root context of \a engine.
327 *
328 * If \c TRANSLATION_DOMAIN is defined, that is also set on
329 * the created context.
330 *
331 * \since 6.8
332 * \relates KLocalizedQmlContext
333 */
334inline KLocalizedQmlContext *setupLocalizedContext(QQmlEngine *engine)
335{
336 auto ctx = Internal::createLocalizedContext(engine);
337#ifdef TRANSLATION_DOMAIN
338 ctx->setTranslationDomain(QStringLiteral(TRANSLATION_DOMAIN));
339#endif
340 return ctx;
341}
342}
343
344#endif
345

source code of ki18n/src/i18n-qml/klocalizedqmlcontext.h