1QTranslator(3qt)                                              QTranslator(3qt)
2
3
4

NAME

6       QTranslator -
7

SYNOPSIS

9       #include <qtranslator.h>
10
11       Inherits QObject.
12
13   Public Members
14       QTranslator ( QObject * parent = 0, const char * name = 0 )
15       ~QTranslator ()
16       QString find ( const char * context, const char * sourceText, const
17           char * comment = 0 ) const  (obsolete)
18       virtual QTranslatorMessage findMessage ( const char * context, const
19           char * sourceText, const char * comment = 0 ) const
20       bool load ( const QString & filename, const QString & directory =
21           QString::null, const QString & search_delimiters = QString::null,
22           const QString & suffix = QString::null )
23       bool load ( const uchar * data, int len )
24       void clear ()
25       enum SaveMode { Everything, Stripped }
26       bool save ( const QString & filename, SaveMode mode = Everything )
27       void insert ( const QTranslatorMessage & message )
28       void insert ( const char * context, const char * sourceText, const
29           QString & translation )  (obsolete)
30       void remove ( const QTranslatorMessage & message )
31       void remove ( const char * context, const char * sourceText )
32           (obsolete)
33       bool contains ( const char * context, const char * sourceText, const
34           char * comment = 0 ) const
35       void squeeze ( SaveMode mode = Everything )
36       void unsqueeze ()
37       QValueList<QTranslatorMessage> messages () const
38       bool isEmpty () const
39

DESCRIPTION

41       The QTranslator class provides internationalization support for text
42       output.
43
44       An object of this class contains a set of QTranslatorMessage objects,
45       each of which specifies a translation from a source language to a
46       target language. QTranslator provides functions to look up
47       translations, add new ones, remove them, load and save them, etc.
48
49       The most common use of QTranslator is to: load a translator file
50       created with Qt Linguist, install it using
51       QApplication::installTranslator(), and use it via QObject::tr(). For
52       example:
53
54           int main( int argc, char ** argv )
55           {
56               QApplication app( argc, argv );
57               QTranslator translator( 0 );
58               translator.load( "french.qm", "." );
59               app.installTranslator( &translator );
60               MyWidget m;
61               app.setMainWidget( &m );
62               m.show();
63               return app.exec();
64           }
65       Note that the translator must be created before the application's main
66       window.
67
68       Most applications will never need to do anything else with this class.
69       The other functions provided by this class are useful for applications
70       that work on translator files.
71
72       We call a translation a "messsage". For this reason, translation files
73       are sometimes referred to as "message files".
74
75       It is possible to lookup a translation using findMessage() (as tr() and
76       QApplication::translate() do) and contains(), to insert a new
77       translation messsage using insert(), and to remove one using remove().
78
79       Translation tools often need more information than the bare source text
80       and translation, for example, context information to help the
81       translator. But end-user programs that are using translations usually
82       only need lookup. To cater for these different needs, QTranslator can
83       use stripped translator files that use the minimum of memory and which
84       support little more functionality than findMessage().
85
86       Thus, load() may not load enough information to make anything more than
87       findMessage() work. save() has an argument indicating whether to save
88       just this minimum of information or to save everything.  Everything"
89       means that for each translation item the following information is kept:
90
91       The translated text - the return value from tr().
92
93       The input key:
94
95       The source text - usually the argument to tr().
96
97       The context - usually the class name for the tr() caller.
98
99       The comment - a comment that helps disambiguate different uses of the
100       same text in the same context.
101
102       The minimum for each item is just the information necessary for
103       findMessage() to return the right text. This may include the source,
104       context and comment, but usually it is just a hash value and the
105       translated text.
106
107       For example, the "Cancel" in a dialog might have "Anuluj" when the
108       program runs in Polish (in this case the source text would be"
109       Cancel"). The context would (normally) be the dialog's class name;
110       there would normally be no comment, and the translated text would be
111       "Anuluj".
112
113       But it's not always so simple. The Spanish version of a printer dialog
114       with settings for two-sided printing and binding would probably require
115       both "Activado" and "Activada" as translations for "Enabled". In this
116       case the source text would be "Enabled" in both cases, and the context
117       would be the dialog's class name, but the two items would have
118       disambiguating comments such as" two-sided printing" for one and
119       "binding" for the other. The comment enables the translator to choose
120       the appropriate gender for the Spanish version, and enables Qt to
121       distinguish between translations.
122
123       Note that when QTranslator loads a stripped file, most functions do not
124       work. The functions that do work with stripped files are explicitly
125       documented as such.
126
127       See also QTranslatorMessage, QApplication::installTranslator(),
128       QApplication::removeTranslator(), QObject::tr(),
129       QApplication::translate(), Environment Classes, and
130       Internationalization with Qt.
131
132   Member Type Documentation

QTranslator::SaveMode

134       This enum type defines how QTranslator writes translation files. There
135       are two modes:
136
137       QTranslator::Everything - files are saved with all available
138       information
139
140       QTranslator::Stripped - files are saved with just enough information
141       for end-user applications
142
143       Note that when QTranslator loads a stripped file, most functions do not
144       work. The functions that do work with stripped files are explicitly
145       documented as such.
146

MEMBER FUNCTION DOCUMENTATION

QTranslator::QTranslator ( QObject * parent = 0, const char * name = 0 )

149       Constructs an empty message file object that is not connected to any
150       file. The object is called name with parent parent.
151

QTranslator::~QTranslator ()

153       Destroys the object and frees any allocated resources.
154

void QTranslator::clear ()

156       Empties this translator of all contents.
157
158       This function works with stripped translator files.
159

bool QTranslator::contains ( const char * context, const char * sourceText,

161       const char * comment = 0 ) const
162       Returns TRUE if this message file contains a message with the key
163       (context, sourceText, comment); otherwise returns FALSE.
164
165       This function works with stripped translator files.
166
167       (This is is a one-liner that calls findMessage().)
168

QString QTranslator::find ( const char * context, const char * sourceText,

170       const char * comment = 0 ) const
171       This function is obsolete. It is provided to keep old source working.
172       We strongly advise against using it in new code.
173
174       Please use findMessage() instead.
175
176       Returns the translation for the key (context, sourceText, comment) or
177       QString::null if there is none in this translator.
178

QTranslatorMessage QTranslator::findMessage ( const char * context, const char

180       * sourceText, const char * comment = 0 ) const [virtual]
181       Returns the QTranslatorMessage for the key (context, sourceText,
182       comment). If none is found, also tries (context, sourceText, "").
183

void QTranslator::insert ( const QTranslatorMessage & message )

185       Inserts message into this message file.
186
187       This function does not work with stripped translator files. It may
188       appear to, but that is not dependable.
189
190       See also remove().
191

void QTranslator::insert ( const char * context, const char * sourceText,

193       const QString & translation )
194       This is an overloaded member function, provided for convenience. It
195       behaves essentially like the above function.
196
197       This function is obsolete. It is provided to keep old source working.
198       We strongly advise against using it in new code.
199

bool QTranslator::isEmpty () const

201       Returns TRUE if this translator is empty, otherwise returns FALSE. This
202       function works with stripped and unstripped translation files.
203

bool QTranslator::load ( const QString & filename, const QString & directory =

205       QString::null, const QString & search_delimiters = QString::null, const
206       QString & suffix = QString::null )
207       Loads filename, which may be an absolute file name or relative to
208       directory. The previous contents of this translator object is
209       discarded. Returns TRUE if the file is loaded successfully; otherwise
210       returns FALSE.
211
212       If the full file name does not exist, other file names are tried in the
213       following order:
214
215       <ol type=1>
216
217       File name with suffix appended (".qm" if the suffix is QString::null).
218
219       File name with text after a character in search_delimiters stripped
220       ("_." is the default for search_delimiters if it is QString::null).
221
222       File name stripped and suffix appended.
223
224       File name stripped further, etc.
225
226       For example, an application running in the fr_CA locale (French-
227       speaking Canada) might call load("foo.fr_ca"," /opt/foolib"). load()
228       would then try to open the first existing readable file from this list:
229
230       <ol type=1>
231
232       /opt/foolib/foo.fr_ca
233
234       /opt/foolib/foo.fr_ca.qm
235
236       /opt/foolib/foo.fr
237
238       /opt/foolib/foo.fr.qm
239
240       /opt/foolib/foo
241
242       /opt/foolib/foo.qm
243
244       See also save().
245
246       Example: i18n/main.cpp.
247

bool QTranslator::load ( const uchar * data, int len )

249       This is an overloaded member function, provided for convenience. It
250       behaves essentially like the above function.
251
252       Loads the .qm file data data of length len into the translator. Returns
253       TRUE if the data is loaded successfully; otherwise returns FALSE.
254
255       The data is not copied. The caller must be able to guarantee that data
256       will not be deleted or modified.
257

QValueList<QTranslatorMessage> QTranslator::messages () const

259       Returns a list of the messages in the translator. This function is
260       rather slow. Because it is seldom called, it's optimized for simplicity
261       and small size, rather than speed.
262
263       If you want to iterate over the list, you should iterate over a copy,
264       e.g.
265
266           QValueList<QTranslatorMessage> list = myTranslator.messages();
267           QValueList<QTranslatorMessage>::Iterator it = list.begin();
268           while ( it != list.end() ) {
269               process_message( *it );
270               ++it;
271           }
272

void QTranslator::remove ( const QTranslatorMessage & message )

274       Removes message from this translator.
275
276       This function works with stripped translator files.
277
278       See also insert().
279

void QTranslator::remove ( const char * context, const char * sourceText )

281       This is an overloaded member function, provided for convenience. It
282       behaves essentially like the above function.
283
284       This function is obsolete. It is provided to keep old source working.
285       We strongly advise against using it in new code.
286
287       Removes the translation associated to the key (context, sourceText," ")
288       from this translator.
289

bool QTranslator::save ( const QString & filename, SaveMode mode = Everything

291       )
292       Saves this message file to filename, overwriting the previous contents
293       of filename. If mode is Everything (the default), all the information
294       is preserved. If mode is Stripped, any information that is not
295       necessary for findMessage() is stripped away.
296
297       See also load().
298

void QTranslator::squeeze ( SaveMode mode = Everything )

300       Converts this message file to the compact format used to store message
301       files on disk.
302
303       You should never need to call this directly; save() and other functions
304       call it as necessary. mode is for internal use.
305
306       See also save() and unsqueeze().
307

void QTranslator::unsqueeze ()

309       Converts this message file into an easily modifiable data structure,
310       less compact than the format used in the files.
311
312       You should never need to call this function; it is called by insert()
313       and friends as necessary.
314
315       See also squeeze().
316
317

SEE ALSO

319       http://doc.trolltech.com/qtranslator.html
320       http://www.trolltech.com/faq/tech.html
321
323       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
324       license file included in the distribution for a complete license
325       statement.
326

AUTHOR

328       Generated automatically from the source code.
329

BUGS

331       If you find a bug in Qt, please report it as described in
332       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
333       help you. Thank you.
334
335       The definitive Qt documentation is provided in HTML format; it is
336       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
337       web browser. This man page is provided as a convenience for those users
338       who prefer man pages, although this format is not officially supported
339       by Trolltech.
340
341       If you find errors in this manual page, please report them to qt-
342       bugs@trolltech.com.  Please include the name of the manual page
343       (qtranslator.3qt) and the Qt version (3.3.8).
344
345
346
347Trolltech AS                    2 February 2007               QTranslator(3qt)
Impressum