KI18n

klocalizedqmlcontext.h
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 klocalizedcontext.h <KLocalizedQmlContext>
23 *
24 * This class is meant to be used to simplify integration of the KI18n framework
25 * in QML.
26 *
27 * The way to do so, is by creating this object and setting it as a context
28 * object:
29 *
30 * @code
31 * QQmlApplicationEngine engine;
32 * auto ctx = new KLocalizedQmlContext(&engine);
33 * engine->rootContext()->setContextObject(ctx);
34 * QQmlEngine::setContextForObject(ctx, engine.rootContext());
35 * ctx->setTranslationDomain(...);
36 * @endcode
37 *
38 * In many cases this can be simplified using KLocalization::setupLocalizedContext():
39 * @code
40 * QQmlApplicationEngine engine;
41 * KLocalization::setupLocalizedContext(&engine);
42 * @endcode
43 *
44 * Then i18n*() and xi18n*() functions should be available for use from the code
45 * loaded in the engine, for the view.
46 *
47 * Unlike its predecessor KLocalizedContext this does automatically trigger
48 * a binding re-evaluation when the application language is changed at runtime
49 * (with Qt 6.6 or higher).
50 *
51 * @note Plural functions differ from the C/C++ version. On QML/JS we can get a
52 * real value easily. To solve warnings on those cases we'll cast the first argument
53 * to make sure it's taken into account for the plural.
54 *
55 * @since 6.8
56 */
57class KI18NQML_EXPORT KLocalizedQmlContext : public QObject
58{
59 Q_OBJECT
60
61 /**
62 * This property only needs to be specified if the context is being run on a library.
63 * in an application there is no need to set the translation domain as the application's
64 * domain can be used.
65 */
66 Q_PROPERTY(QString translationDomain READ translationDomain WRITE setTranslationDomain NOTIFY translationDomainChanged)
67
68public:
69 explicit KLocalizedQmlContext(QObject *parent = nullptr);
70 ~KLocalizedQmlContext() override;
71
72 QString translationDomain() const;
73 void setTranslationDomain(const QString &domain);
74
75 Q_INVOKABLE QString i18n(const QString &message,
76 const QVariant &param1 = QVariant(),
77 const QVariant &param2 = QVariant(),
78 const QVariant &param3 = QVariant(),
79 const QVariant &param4 = QVariant(),
80 const QVariant &param5 = QVariant(),
81 const QVariant &param6 = QVariant(),
82 const QVariant &param7 = QVariant(),
83 const QVariant &param8 = QVariant(),
84 const QVariant &param9 = QVariant(),
85 const QVariant &param10 = QVariant()) const;
86
87 Q_INVOKABLE QString i18nc(const QString &context,
88 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 i18np(const QString &singular,
101 const QString &plural,
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 i18ncp(const QString &context,
114 const QString &singular,
115 const QString &plural,
116 const QVariant &param1 = QVariant(),
117 const QVariant &param2 = QVariant(),
118 const QVariant &param3 = QVariant(),
119 const QVariant &param4 = QVariant(),
120 const QVariant &param5 = QVariant(),
121 const QVariant &param6 = QVariant(),
122 const QVariant &param7 = QVariant(),
123 const QVariant &param8 = QVariant(),
124 const QVariant &param9 = QVariant(),
125 const QVariant &param10 = QVariant()) const;
126
127 Q_INVOKABLE QString i18nd(const QString &domain,
128 const QString &message,
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 i18ndc(const QString &domain,
141 const QString &context,
142 const QString &message,
143 const QVariant &param1 = QVariant(),
144 const QVariant &param2 = QVariant(),
145 const QVariant &param3 = QVariant(),
146 const QVariant &param4 = QVariant(),
147 const QVariant &param5 = QVariant(),
148 const QVariant &param6 = QVariant(),
149 const QVariant &param7 = QVariant(),
150 const QVariant &param8 = QVariant(),
151 const QVariant &param9 = QVariant(),
152 const QVariant &param10 = QVariant()) const;
153
154 Q_INVOKABLE QString i18ndp(const QString &domain,
155 const QString &singular,
156 const QString &plural,
157 const QVariant &param1 = QVariant(),
158 const QVariant &param2 = QVariant(),
159 const QVariant &param3 = QVariant(),
160 const QVariant &param4 = QVariant(),
161 const QVariant &param5 = QVariant(),
162 const QVariant &param6 = QVariant(),
163 const QVariant &param7 = QVariant(),
164 const QVariant &param8 = QVariant(),
165 const QVariant &param9 = QVariant(),
166 const QVariant &param10 = QVariant()) const;
167
168 Q_INVOKABLE QString i18ndcp(const QString &domain,
169 const QString &context,
170 const QString &singular,
171 const QString &plural,
172 const QVariant &param1 = QVariant(),
173 const QVariant &param2 = QVariant(),
174 const QVariant &param3 = QVariant(),
175 const QVariant &param4 = QVariant(),
176 const QVariant &param5 = QVariant(),
177 const QVariant &param6 = QVariant(),
178 const QVariant &param7 = QVariant(),
179 const QVariant &param8 = QVariant(),
180 const QVariant &param9 = QVariant(),
181 const QVariant &param10 = QVariant()) const;
182
183 Q_INVOKABLE QString xi18n(const QString &message,
184 const QVariant &param1 = QVariant(),
185 const QVariant &param2 = QVariant(),
186 const QVariant &param3 = QVariant(),
187 const QVariant &param4 = QVariant(),
188 const QVariant &param5 = QVariant(),
189 const QVariant &param6 = QVariant(),
190 const QVariant &param7 = QVariant(),
191 const QVariant &param8 = QVariant(),
192 const QVariant &param9 = QVariant(),
193 const QVariant &param10 = QVariant()) const;
194
195 Q_INVOKABLE QString xi18nc(const QString &context,
196 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 xi18np(const QString &singular,
209 const QString &plural,
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 xi18ncp(const QString &context,
222 const QString &singular,
223 const QString &plural,
224 const QVariant &param1 = QVariant(),
225 const QVariant &param2 = QVariant(),
226 const QVariant &param3 = QVariant(),
227 const QVariant &param4 = QVariant(),
228 const QVariant &param5 = QVariant(),
229 const QVariant &param6 = QVariant(),
230 const QVariant &param7 = QVariant(),
231 const QVariant &param8 = QVariant(),
232 const QVariant &param9 = QVariant(),
233 const QVariant &param10 = QVariant()) const;
234
235 Q_INVOKABLE QString xi18nd(const QString &domain,
236 const QString &message,
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 xi18ndc(const QString &domain,
249 const QString &context,
250 const QString &message,
251 const QVariant &param1 = QVariant(),
252 const QVariant &param2 = QVariant(),
253 const QVariant &param3 = QVariant(),
254 const QVariant &param4 = QVariant(),
255 const QVariant &param5 = QVariant(),
256 const QVariant &param6 = QVariant(),
257 const QVariant &param7 = QVariant(),
258 const QVariant &param8 = QVariant(),
259 const QVariant &param9 = QVariant(),
260 const QVariant &param10 = QVariant()) const;
261
262 Q_INVOKABLE QString xi18ndp(const QString &domain,
263 const QString &singular,
264 const QString &plural,
265 const QVariant &param1 = QVariant(),
266 const QVariant &param2 = QVariant(),
267 const QVariant &param3 = QVariant(),
268 const QVariant &param4 = QVariant(),
269 const QVariant &param5 = QVariant(),
270 const QVariant &param6 = QVariant(),
271 const QVariant &param7 = QVariant(),
272 const QVariant &param8 = QVariant(),
273 const QVariant &param9 = QVariant(),
274 const QVariant &param10 = QVariant()) const;
275
276 Q_INVOKABLE QString xi18ndcp(const QString &domain,
277 const QString &context,
278 const QString &singular,
279 const QString &plural,
280 const QVariant &param1 = QVariant(),
281 const QVariant &param2 = QVariant(),
282 const QVariant &param3 = QVariant(),
283 const QVariant &param4 = QVariant(),
284 const QVariant &param5 = QVariant(),
285 const QVariant &param6 = QVariant(),
286 const QVariant &param7 = QVariant(),
287 const QVariant &param8 = QVariant(),
288 const QVariant &param9 = QVariant(),
289 const QVariant &param10 = QVariant()) const;
290
291Q_SIGNALS:
292 void translationDomainChanged(const QString &translationDomain);
293
294private:
295 bool eventFilter(QObject *watched, QEvent *event) override;
296 std::unique_ptr<KLocalizedQmlContextPrivate> const d;
297};
298
299namespace KLocalization
300{
301///@cond internal
302namespace Internal
303{
304[[nodiscard]] KI18NQML_EXPORT KLocalizedQmlContext *createLocalizedContext(QQmlEngine *engine);
305}
306///@endcond
307
308/** Creates a KLocalizedQmlContext engine and sets it up in the
309 * root context of @p engine.
310 *
311 * If @p TRANSLATION_DOMAIN is defined, that is also set on
312 * the created context.
313 *
314 * @since 6.8
315 */
316inline KLocalizedQmlContext *setupLocalizedContext(QQmlEngine *engine)
317{
318 auto ctx = Internal::createLocalizedContext(engine);
319#ifdef TRANSLATION_DOMAIN
320 ctx->setTranslationDomain(QStringLiteral(TRANSLATION_DOMAIN));
321#endif
322 return ctx;
323}
324}
325
326#endif
KLocalizedQmlContext
This class is meant to be used to simplify integration of the KI18n framework in QML.
Definition klocalizedqmlcontext.h:58
KLocalizedQmlContext::translationDomain
QString translationDomain
This property only needs to be specified if the context is being run on a library.
Definition klocalizedqmlcontext.h:66
i18ndcp
QString i18ndcp(const char *domain, const char *context, const char *singular, const char *plural, const TYPE &arg...)
Translate a string from domain with context and plural and substitute any arguments.
xi18np
QString xi18np(const char *singular, const char *plural, const TYPE &arg...)
Translate a markup-aware string with plural and substitute any arguments.
i18np
QString i18np(const char *singular, const char *plural, const TYPE &arg...)
Translate a string with plural and substitute any arguments.
i18ndc
QString i18ndc(const char *domain, const char *context, const char *text, const TYPE &arg...)
Translate a string from domain with context and substitute any arguments.
xi18ncp
QString xi18ncp(const char *context, const char *singular, const char *plural, const TYPE &arg...)
Translate a markup-aware string with context and plural and substitute any arguments.
xi18nc
QString xi18nc(const char *context, const char *text, const TYPE &arg...)
Translate a markup-aware string with context and substitute any arguments.
i18nc
QString i18nc(const char *context, const char *text, const TYPE &arg...)
Translate a string with context and substitute any arguments.
xi18ndp
QString xi18ndp(const char *domain, const char *singular, const char *plural, const TYPE &arg...)
Translate a markup-aware string from domain with plural and substitute any arguments.
xi18ndcp
QString xi18ndcp(const char *domain, const char *context, const char *singular, const char *plural, const TYPE &arg...)
Translate a markup-aware string from domain with context and plural and substitute any arguments.
xi18nd
QString xi18nd(const char *domain, const char *text, const TYPE &arg...)
Translate a markup-aware string from domain and substitute any arguments.
xi18n
QString xi18n(const char *text, const TYPE &arg...)
Translate a markup-aware string and substitute any arguments.
i18ndp
QString i18ndp(const char *domain, const char *singular, const char *plural, const TYPE &arg...)
Translate a string from domain with plural and substitute any arguments.
i18nd
QString i18nd(const char *domain, const char *text, const TYPE &arg...)
Translate a string from domain and substitute any arguments.
xi18ndc
QString xi18ndc(const char *domain, const char *context, const char *text, const TYPE &arg...)
Translate a markup-aware string from domain with context and substitute any arguments.
i18n
QString i18n(const char *text, const TYPE &arg...)
Translate a string and substitute any arguments.
i18ncp
QString i18ncp(const char *context, const char *singular, const char *plural, const TYPE &arg...)
Translate a string with context and plural and substitute any arguments.
KLocalization
Namespace containing helpers for localization.
Definition klocalizedqmlcontext.h:300
KLocalization::setupLocalizedContext
KLocalizedQmlContext * setupLocalizedContext(QQmlEngine *engine)
Creates a KLocalizedQmlContext engine and sets it up in the root context of engine.
Definition klocalizedqmlcontext.h:316
QObject::QObject
QObject(QObject *parent)
QObject::Q_INVOKABLE
Q_INVOKABLEQ_INVOKABLE
QObject::Q_OBJECT
Q_OBJECTQ_OBJECT
QObject::Q_PROPERTY
Q_PROPERTY(...)
QObject::Q_SIGNALS
Q_SIGNALSQ_SIGNALS
QObject::event
virtual bool event(QEvent *e)
QObject::eventFilter
virtual bool eventFilter(QObject *watched, QEvent *event)
QObject::parent
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 24 2025 11:48:51 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.