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 <QtQmlIntegration>
16#include <memory>
17
18class QQmlEngine;
19
20class KLocalizedQmlContextPrivate;
21
22/*!
23 * \class KLocalizedQmlContext
24 * \inmodule KI18nQml
25 *
26 * \brief This class is meant to be used to simplify integration of the KI18n framework
27 * in QML.
28 *
29 * The way to do so, is by creating this object and setting it as a context
30 * object:
31 *
32 * \code
33 * QQmlApplicationEngine engine;
34 * auto ctx = new KLocalizedQmlContext(&engine);
35 * engine->rootContext()->setContextObject(ctx);
36 * QQmlEngine::setContextForObject(ctx, engine.rootContext());
37 * ctx->setTranslationDomain(...);
38 * \endcode
39 *
40 * In many cases this can be simplified using KLocalization::setupLocalizedContext():
41 * \code
42 * QQmlApplicationEngine engine;
43 * KLocalization::setupLocalizedContext(&engine);
44 * \endcode
45 *
46 * Then KI18n.i18n*() and KI18n.xi18n*() functions should be available for use from the code
47 * loaded in the engine, for the view.
48 *
49 * Unlike its predecessor KLocalizedContext this does automatically trigger
50 * a binding re-evaluation when the application language is changed at runtime
51 * (with Qt 6.6 or higher).
52 *
53 * \note Plural functions differ from the C/C++ version. On QML/JS we can get a
54 * real value easily. To solve warnings on those cases we'll cast the first argument
55 * to make sure it's taken into account for the plural.
56 *
57 * \warning For history reasons the i18n functions are also available on the root context without KI18n.* prefix.
58 * It is very recommended to use the KI18n.* version moving forward, so QML tooling like qmlls and qmllint can inspect
59 * the API calls. KI18n.* was introduced in version 6.21.
60 *
61 * \since 6.8
62 */
63
64/*!
65 \qmltype KI18n
66 \since 6.21
67 \nativetype KLocalizedQmlContext
68 \inqmlmodule org.kde.ki18n
69 \brief Advanced internationalization support for QML.
70
71 \sa KLocalizedQmlContext::KLocalizedQmlContext()
72
73 To use it, create an instance and set it as the context object of your QML engine in C++:
74
75 \code
76 QQmlApplicationEngine engine;
77 KLocalization::setupLocalizedContext(&engine);
78 \endcode
79
80 Then you can use the KI18n.i18n*() and KI18n.xi18n*() functions from QML code, for example:
81
82 \qml
83 import QtQuick
84 import org.kde.ki18n
85 Text {
86 text: KI18n.i18nc("@label", "Hello World")
87 }
88 \endqml
89*/
90
91/*!
92 \qmltype KI18nContext
93 \since 6.23
94 \nativetype KLocalizedQmlContext
95 \inherits KI18n
96 \inqmlmodule org.kde.ki18n
97 \brief Creatable variant of KI18n
98
99 \sa KI18n
100 \sa KLocalizedQmlContext::KLocalizedQmlContext()
101
102 This is a creatable variant of KI18n and may be used to create multiple localized contexts right from within QML.
103 In particular useful when working with multiple translation domains (such as in library use cases).
104
105 Unlike the KI18n variant this does not require help from the C++ side and can be used entirely from QML:
106
107 \qml
108 readonly property KI18nContext libI18n: KI18nContext {
109 translationDomain: "librocketship"
110 }
111 text: libI18n.i18nc("@title", "Welcome to Space")
112 \endqml
113*/
114class KI18NQML_EXPORT KLocalizedQmlContext : public QObject
115{
116 Q_OBJECT
117
118 /*!
119 * \property KLocalizedQmlContext::translationDomain
120 *
121 * This property only needs to be specified if the context is being run on a library.
122 * in an application there is no need to set the translation domain as the application's
123 * domain can be used.
124 */
125 /*!
126 \qmlproperty string KI18nContext::translationDomain
127
128 The translation domain to use for this context. This must be explicitly set for the KI18nContext to be functional.
129 */
130 Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain NOTIFY translationDomainChanged)
131
132 QML_ELEMENT
133 QML_NAMED_ELEMENT(KI18nContext)
134
135public:
136 /*!
137 *
138 */
139 explicit KLocalizedQmlContext(QObject *parent = nullptr);
140 ~KLocalizedQmlContext() override;
141
142 /*!
143 *
144 */
145 QString translationDomain() const;
146
147 /*!
148 *
149 */
150 void setTranslationDomain(const QString &domain);
151
152 /*!
153 \qmlmethod string KI18n::i18n(message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined, param4: variant =
154 undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined, param9: variant =
155 undefined, param10: variant = undefined)
156 \sa KLocalizedString::i18n()
157 */
158 Q_INVOKABLE QString i18n(const QString &message,
159 const QVariant &param1 = QVariant(),
160 const QVariant &param2 = QVariant(),
161 const QVariant &param3 = QVariant(),
162 const QVariant &param4 = QVariant(),
163 const QVariant &param5 = QVariant(),
164 const QVariant &param6 = QVariant(),
165 const QVariant &param7 = QVariant(),
166 const QVariant &param8 = QVariant(),
167 const QVariant &param9 = QVariant(),
168 const QVariant &param10 = QVariant()) const;
169
170 /*!
171 \qmlmethod string KI18n::i18nc(context: string, message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
172 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
173 param9: variant = undefined, param10: variant = undefined)
174 \sa KLocalizedString::i18nc()
175 */
176 Q_INVOKABLE QString i18nc(const QString &context,
177 const QString &message,
178 const QVariant &param1 = QVariant(),
179 const QVariant &param2 = QVariant(),
180 const QVariant &param3 = QVariant(),
181 const QVariant &param4 = QVariant(),
182 const QVariant &param5 = QVariant(),
183 const QVariant &param6 = QVariant(),
184 const QVariant &param7 = QVariant(),
185 const QVariant &param8 = QVariant(),
186 const QVariant &param9 = QVariant(),
187 const QVariant &param10 = QVariant()) const;
188
189 /*!
190 \qmlmethod string KI18n::i18np(singular: string, plural: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
191 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
192 param9: variant = undefined, param10: variant = undefined)
193 \sa KLocalizedString::i18np()
194 */
195 Q_INVOKABLE QString i18np(const QString &singular,
196 const QString &plural,
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 /*!
209 \qmlmethod string KI18n::i18ncp(context: string, singular: string, plural: string, param1: variant = undefined, param2: variant = undefined,
210 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
211 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
212 \sa KLocalizedString::i18ncp()
213 */
214 Q_INVOKABLE QString i18ncp(const QString &context,
215 const QString &singular,
216 const QString &plural,
217 const QVariant &param1 = QVariant(),
218 const QVariant &param2 = QVariant(),
219 const QVariant &param3 = QVariant(),
220 const QVariant &param4 = QVariant(),
221 const QVariant &param5 = QVariant(),
222 const QVariant &param6 = QVariant(),
223 const QVariant &param7 = QVariant(),
224 const QVariant &param8 = QVariant(),
225 const QVariant &param9 = QVariant(),
226 const QVariant &param10 = QVariant()) const;
227
228 /*!
229 \qmlmethod string KI18n::i18nd(domain: string, message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
230 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
231 param9: variant = undefined, param10: variant = undefined)
232 \sa KLocalizedString::i18nd()
233 */
234 Q_INVOKABLE QString i18nd(const QString &domain,
235 const QString &message,
236 const QVariant &param1 = QVariant(),
237 const QVariant &param2 = QVariant(),
238 const QVariant &param3 = QVariant(),
239 const QVariant &param4 = QVariant(),
240 const QVariant &param5 = QVariant(),
241 const QVariant &param6 = QVariant(),
242 const QVariant &param7 = QVariant(),
243 const QVariant &param8 = QVariant(),
244 const QVariant &param9 = QVariant(),
245 const QVariant &param10 = QVariant()) const;
246
247 /*!
248 \qmlmethod string KI18n::i18ndc(domain: string, context: string, message: string, param1: variant = undefined, param2: variant = undefined,
249 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
250 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
251 \sa KLocalizedString::i18ndc()
252 */
253 Q_INVOKABLE QString i18ndc(const QString &domain,
254 const QString &context,
255 const QString &message,
256 const QVariant &param1 = QVariant(),
257 const QVariant &param2 = QVariant(),
258 const QVariant &param3 = QVariant(),
259 const QVariant &param4 = QVariant(),
260 const QVariant &param5 = QVariant(),
261 const QVariant &param6 = QVariant(),
262 const QVariant &param7 = QVariant(),
263 const QVariant &param8 = QVariant(),
264 const QVariant &param9 = QVariant(),
265 const QVariant &param10 = QVariant()) const;
266
267 /*!
268 \qmlmethod string KI18n::i18ndp(domain: string, singular: string, plural: string, param1: variant = undefined, param2: variant = undefined,
269 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
270 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
271 \sa KLocalizedString::i18ndp()
272 */
273 Q_INVOKABLE QString i18ndp(const QString &domain,
274 const QString &singular,
275 const QString &plural,
276 const QVariant &param1 = QVariant(),
277 const QVariant &param2 = QVariant(),
278 const QVariant &param3 = QVariant(),
279 const QVariant &param4 = QVariant(),
280 const QVariant &param5 = QVariant(),
281 const QVariant &param6 = QVariant(),
282 const QVariant &param7 = QVariant(),
283 const QVariant &param8 = QVariant(),
284 const QVariant &param9 = QVariant(),
285 const QVariant &param10 = QVariant()) const;
286
287 /*!
288 \qmlmethod string KI18n::i18ndcp(domain: string, context: string, singular: string, plural: string, param1: variant = undefined,
289 param2: variant = undefined, param3: variant = undefined, param4: variant = undefined, param5: variant = undefined,
290 param6: variant = undefined, param7: variant = undefined, param8: variant = undefined, param9: variant = undefined,
291 param10: variant = undefined)
292 \sa KLocalizedString::i18ndcp()
293 */
294 Q_INVOKABLE QString i18ndcp(const QString &domain,
295 const QString &context,
296 const QString &singular,
297 const QString &plural,
298 const QVariant &param1 = QVariant(),
299 const QVariant &param2 = QVariant(),
300 const QVariant &param3 = QVariant(),
301 const QVariant &param4 = QVariant(),
302 const QVariant &param5 = QVariant(),
303 const QVariant &param6 = QVariant(),
304 const QVariant &param7 = QVariant(),
305 const QVariant &param8 = QVariant(),
306 const QVariant &param9 = QVariant(),
307 const QVariant &param10 = QVariant()) const;
308
309 /*!
310 \qmlmethod string KI18n::xi18n(message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined, param4: variant =
311 undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined, param9: variant =
312 undefined, param10: variant = undefined)
313 \sa KLocalizedString::xi18n()
314 */
315 Q_INVOKABLE QString xi18n(const QString &message,
316 const QVariant &param1 = QVariant(),
317 const QVariant &param2 = QVariant(),
318 const QVariant &param3 = QVariant(),
319 const QVariant &param4 = QVariant(),
320 const QVariant &param5 = QVariant(),
321 const QVariant &param6 = QVariant(),
322 const QVariant &param7 = QVariant(),
323 const QVariant &param8 = QVariant(),
324 const QVariant &param9 = QVariant(),
325 const QVariant &param10 = QVariant()) const;
326
327 /*!
328 \qmlmethod string KI18n::xi18nc(context: string, message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
329 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
330 param9: variant = undefined, param10: variant = undefined)
331 \sa KLocalizedString::xi18nc()
332 */
333 Q_INVOKABLE QString xi18nc(const QString &context,
334 const QString &message,
335 const QVariant &param1 = QVariant(),
336 const QVariant &param2 = QVariant(),
337 const QVariant &param3 = QVariant(),
338 const QVariant &param4 = QVariant(),
339 const QVariant &param5 = QVariant(),
340 const QVariant &param6 = QVariant(),
341 const QVariant &param7 = QVariant(),
342 const QVariant &param8 = QVariant(),
343 const QVariant &param9 = QVariant(),
344 const QVariant &param10 = QVariant()) const;
345
346 /*!
347 \qmlmethod string KI18n::xi18np(singular: string, plural: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
348 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
349 param9: variant = undefined, param10: variant = undefined)
350 \sa KLocalizedString::xi18np()
351 */
352 Q_INVOKABLE QString xi18np(const QString &singular,
353 const QString &plural,
354 const QVariant &param1 = QVariant(),
355 const QVariant &param2 = QVariant(),
356 const QVariant &param3 = QVariant(),
357 const QVariant &param4 = QVariant(),
358 const QVariant &param5 = QVariant(),
359 const QVariant &param6 = QVariant(),
360 const QVariant &param7 = QVariant(),
361 const QVariant &param8 = QVariant(),
362 const QVariant &param9 = QVariant(),
363 const QVariant &param10 = QVariant()) const;
364
365 /*!
366 \qmlmethod string KI18n::xi18ncp(context: string, singular: string, plural: string, param1: variant = undefined, param2: variant = undefined,
367 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
368 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
369 \sa KLocalizedString::xi18ncp()
370 */
371 Q_INVOKABLE QString xi18ncp(const QString &context,
372 const QString &singular,
373 const QString &plural,
374 const QVariant &param1 = QVariant(),
375 const QVariant &param2 = QVariant(),
376 const QVariant &param3 = QVariant(),
377 const QVariant &param4 = QVariant(),
378 const QVariant &param5 = QVariant(),
379 const QVariant &param6 = QVariant(),
380 const QVariant &param7 = QVariant(),
381 const QVariant &param8 = QVariant(),
382 const QVariant &param9 = QVariant(),
383 const QVariant &param10 = QVariant()) const;
384
385 /*!
386 \qmlmethod string KI18n::xi18nd(domain: string, message: string, param1: variant = undefined, param2: variant = undefined, param3: variant = undefined,
387 param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined, param8: variant = undefined,
388 param9: variant = undefined, param10: variant = undefined)
389 \sa KLocalizedString::xi18nd()
390 */
391 Q_INVOKABLE QString xi18nd(const QString &domain,
392 const QString &message,
393 const QVariant &param1 = QVariant(),
394 const QVariant &param2 = QVariant(),
395 const QVariant &param3 = QVariant(),
396 const QVariant &param4 = QVariant(),
397 const QVariant &param5 = QVariant(),
398 const QVariant &param6 = QVariant(),
399 const QVariant &param7 = QVariant(),
400 const QVariant &param8 = QVariant(),
401 const QVariant &param9 = QVariant(),
402 const QVariant &param10 = QVariant()) const;
403
404 /*!
405 \qmlmethod string KI18n::xi18ndc(domain: string, context: string, message: string, param1: variant = undefined, param2: variant = undefined,
406 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
407 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
408 \sa KLocalizedString::xi18ndc()
409 */
410 Q_INVOKABLE QString xi18ndc(const QString &domain,
411 const QString &context,
412 const QString &message,
413 const QVariant &param1 = QVariant(),
414 const QVariant &param2 = QVariant(),
415 const QVariant &param3 = QVariant(),
416 const QVariant &param4 = QVariant(),
417 const QVariant &param5 = QVariant(),
418 const QVariant &param6 = QVariant(),
419 const QVariant &param7 = QVariant(),
420 const QVariant &param8 = QVariant(),
421 const QVariant &param9 = QVariant(),
422 const QVariant &param10 = QVariant()) const;
423
424 /*!
425 \qmlmethod string KI18n::xi18ndp(domain: string, singular: string, plural: string, param1: variant = undefined, param2: variant = undefined,
426 param3: variant = undefined, param4: variant = undefined, param5: variant = undefined, param6: variant = undefined, param7: variant = undefined,
427 param8: variant = undefined, param9: variant = undefined, param10: variant = undefined)
428 \sa KLocalizedString::xi18ndp()
429 */
430 Q_INVOKABLE QString xi18ndp(const QString &domain,
431 const QString &singular,
432 const QString &plural,
433 const QVariant &param1 = QVariant(),
434 const QVariant &param2 = QVariant(),
435 const QVariant &param3 = QVariant(),
436 const QVariant &param4 = QVariant(),
437 const QVariant &param5 = QVariant(),
438 const QVariant &param6 = QVariant(),
439 const QVariant &param7 = QVariant(),
440 const QVariant &param8 = QVariant(),
441 const QVariant &param9 = QVariant(),
442 const QVariant &param10 = QVariant()) const;
443
444 /*!
445 \qmlmethod string KI18n::xi18ndcp(domain: string, context: string, singular: string, plural: string, param1: variant = undefined,
446 param2: variant = undefined, param3: variant = undefined, param4: variant = undefined, param5: variant = undefined,
447 param6: variant = undefined, param7: variant = undefined, param8: variant = undefined, param9: variant = undefined,
448 param10: variant = undefined)
449 \sa KLocalizedString::xi18ndcp()
450 */
451 Q_INVOKABLE QString xi18ndcp(const QString &domain,
452 const QString &context,
453 const QString &singular,
454 const QString &plural,
455 const QVariant &param1 = QVariant(),
456 const QVariant &param2 = QVariant(),
457 const QVariant &param3 = QVariant(),
458 const QVariant &param4 = QVariant(),
459 const QVariant &param5 = QVariant(),
460 const QVariant &param6 = QVariant(),
461 const QVariant &param7 = QVariant(),
462 const QVariant &param8 = QVariant(),
463 const QVariant &param9 = QVariant(),
464 const QVariant &param10 = QVariant()) const;
465
466Q_SIGNALS:
467 void translationDomainChanged(const QString &translationDomain);
468
469private:
470 std::unique_ptr<KLocalizedQmlContextPrivate> const d;
471};
472
473/*!
474 * \namespace KLocalization
475 * \inmodule KI18nQml
476 * \brief Namespace containing helpers for localization.
477 */
478namespace KLocalization
479{
480namespace Internal
481{
482[[nodiscard]] KI18NQML_EXPORT KLocalizedQmlContext *createLocalizedContext(QQmlEngine *engine);
483}
484
485/*!
486 * Creates a KLocalizedQmlContext engine and sets it up in the
487 * root context of \a engine.
488 *
489 * If \c TRANSLATION_DOMAIN is defined, that is also set on
490 * the created context.
491 *
492 * \since 6.8
493 * \relates KLocalizedQmlContext
494 */
495inline KLocalizedQmlContext *setupLocalizedContext(QQmlEngine *engine)
496{
497 auto ctx = Internal::createLocalizedContext(engine);
498#ifdef TRANSLATION_DOMAIN
499 ctx->setTranslationDomain(QStringLiteral(TRANSLATION_DOMAIN));
500#endif
501 return ctx;
502}
503}
504
505#endif
506

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