Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qttranslation.qdoc
Go to the documentation of this file.
1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \headerfile <QtTranslation>
6 \inmodule QtCore
7 \ingroup funclists
8 \brief Marking strings for translation.
9
10 \sa {Writing Source Code for Translation}
11*/
12
13/*!
14 \macro QT_TR_NOOP(sourceText)
15 \relates <QtTranslation>
16
17 Marks the UTF-8 encoded string literal \a sourceText for delayed
18 translation in the current context (class).
19
20 The macro tells lupdate to collect the string, and expands to
21 \a sourceText itself.
22
23 Example:
24
25 \snippet code/src_corelib_global_qglobal.cpp 34
26
27 The macro QT_TR_NOOP_UTF8() is identical and obsolete; this applies
28 to all other _UTF8 macros as well.
29
30 \sa QT_TRANSLATE_NOOP(), {Internationalization with Qt}
31*/
32
33/*!
34 \macro QT_TRANSLATE_NOOP(context, sourceText)
35 \relates <QtTranslation>
36
37 Marks the UTF-8 encoded string literal \a sourceText for delayed
38 translation in the given \a context. The \a context is typically
39 a class name and also needs to be specified as a string literal.
40
41 The macro tells lupdate to collect the string, and expands to
42 \a sourceText itself.
43
44 Example:
45
46 \snippet code/src_corelib_global_qglobal_widgets.cpp 3
47
48 \sa QT_TR_NOOP(), QT_TRANSLATE_NOOP3(), {Internationalization with Qt}
49*/
50
51/*!
52 \macro QT_TRANSLATE_NOOP3(context, sourceText, disambiguation)
53 \relates <QtTranslation>
54 \since 4.4
55
56 Marks the UTF-8 encoded string literal \a sourceText for delayed
57 translation in the given \a context with the given \a disambiguation.
58 The \a context is typically a class and also needs to be specified
59 as a string literal. The string literal \a disambiguation should be
60 a short semantic tag to tell apart otherwise identical strings.
61
62 The macro tells lupdate to collect the string, and expands to an
63 anonymous struct of the two string literals passed as \a sourceText
64 and \a disambiguation.
65
66 Example:
67
68 \snippet code/src_corelib_global_qglobal_widgets.cpp 4
69
70 \sa QT_TR_NOOP(), QT_TRANSLATE_NOOP(), {Internationalization with Qt}
71*/
72
73/*!
74 \macro QT_TR_N_NOOP(sourceText)
75 \relates <QtTranslation>
76 \since 5.12
77
78 Marks the UTF-8 encoded string literal \a sourceText for numerator
79 dependent delayed translation in the current context (class).
80
81 The macro tells lupdate to collect the string, and expands to
82 \a sourceText itself.
83
84 The macro expands to \a sourceText.
85
86 Example:
87
88 \snippet code/src_corelib_global_qglobal.cpp qttrnnoop
89
90 \sa QT_TR_NOOP, {Internationalization with Qt}
91*/
92
93/*!
94 \macro QT_TRANSLATE_N_NOOP(context, sourceText)
95 \relates <QtTranslation>
96 \since 5.12
97
98 Marks the UTF-8 encoded string literal \a sourceText for numerator
99 dependent delayed translation in the given \a context.
100 The \a context is typically a class name and also needs to be
101 specified as a string literal.
102
103 The macro tells lupdate to collect the string, and expands to
104 \a sourceText itself.
105
106 Example:
107
108 \snippet code/src_corelib_global_qglobal.cpp qttranslatennoop
109
110 \sa QT_TRANSLATE_NOOP(), QT_TRANSLATE_N_NOOP3(),
111 {Internationalization with Qt}
112*/
113
114/*!
115 \macro QT_TRANSLATE_N_NOOP3(context, sourceText, comment)
116 \relates <QtTranslation>
117 \since 5.12
118
119 Marks the UTF-8 encoded string literal \a sourceText for numerator
120 dependent delayed translation in the given \a context with the given
121 \a comment.
122 The \a context is typically a class and also needs to be specified
123 as a string literal. The string literal \a comment should be
124 a short semantic tag to tell apart otherwise identical strings.
125
126 The macro tells lupdate to collect the string, and expands to an
127 anonymous struct of the two string literals passed as \a sourceText
128 and \a comment.
129
130 Example:
131
132 \snippet code/src_corelib_global_qglobal_widgets.cpp qttranslatennoop
133
134 \sa QT_TR_NOOP(), QT_TRANSLATE_NOOP(), QT_TRANSLATE_NOOP3(),
135 {Internationalization with Qt}
136*/
137
138/*!
139 \fn QString qtTrId(const char *id, int n = -1)
140 \relates <QtTranslation>
141 \reentrant
142 \since 4.6
143
144 \brief The qtTrId function finds and returns a translated string.
145
146 Returns a translated string identified by \a id.
147 If no matching string is found, the id itself is returned. This
148 should not happen under normal conditions.
149
150 If \a n >= 0, all occurrences of \c %n in the resulting string
151 are replaced with a decimal representation of \a n. In addition,
152 depending on \a n's value, the translation text may vary.
153
154 Meta data and comments can be passed as documented for QObject::tr().
155 In addition, it is possible to supply a source string template like that:
156
157 \tt{//% <C string>}
158
159 or
160
161 \tt{\\begincomment% <C string> \\endcomment}
162
163 Example:
164
165 \snippet code/src_corelib_global_qglobal.cpp qttrid
166
167 Creating QM files suitable for use with this function requires passing
168 the \c -idbased option to the \c lrelease tool.
169
170 \warning This method is reentrant only if all translators are
171 installed \e before calling this method. Installing or removing
172 translators while performing translations is not supported. Doing
173 so will probably result in crashes or other undesirable behavior.
174
175 \sa QObject::tr(), QCoreApplication::translate(), {Internationalization with Qt}
176*/
177
178/*!
179 \fn QString qTrId(const char *id, int n = -1)
180 \relates <QtTranslation>
181 \reentrant
182 \since 6.9
183
184 \brief The qTrId function is an alias for qtTrId.
185
186 This function provides the same functionality as qtTrId(). It returns
187 a translated string identified by \a id. If no matching string is found,
188 the id itself is returned.
189
190 If \a n >= 0, all occurrences of \c %n in the resulting string
191 are replaced with a decimal representation of \a n. In addition,
192 depending on \a n's value, the translation text may vary.
193
194 Both qTrId() and qtTrId() can be used interchangeably.
195
196 \sa qtTrId(), QObject::tr(), QCoreApplication::translate(), {Internationalization with Qt}
197*/
198
199/*!
200 \macro QT_TRID_NOOP(id)
201 \relates <QtTranslation>
202 \since 4.6
203
204 \brief The QT_TRID_NOOP macro marks an id for dynamic translation.
205
206 The only purpose of this macro is to provide an anchor for attaching
207 meta data like to qtTrId().
208
209 The macro expands to \a id.
210
211 Example:
212
213 \snippet code/src_corelib_global_qglobal_widgets.cpp qttrid_noop
214
215 \sa qtTrId(), {Internationalization with Qt}
216*/
217
218/*!
219 \macro QT_TRID_N_NOOP(id)
220 \relates <QtTranslation>
221 \since 6.3
222
223 \brief The QT_TRID_N_NOOP macro marks an id for numerator
224 dependent dynamic translation.
225
226 The only purpose of this macro is to provide an anchor for attaching
227 meta data like to qtTrId().
228
229 The macro expands to \a id.
230
231 Example:
232
233 \snippet code/src_corelib_global_qglobal.cpp qttrid_n_noop
234
235 \sa qtTrId(), {Internationalization with Qt}
236*/