1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
43 \page linguist-manual.html
44 \title Qt Linguist Manual
47 \startpage {index.html}{Qt Reference Documentation}
48 \nextpage Qt Linguist Manual: Release Manager
52 Qt provides excellent support for translating applications into local
53 languages. This Guide explains how to use Qt's translation tools for
54 each of the roles involved in translating an application. The Guide
55 begins with a brief overview of the issues that must be considered,
56 followed by chapters devoted to each role and the supporting tools
59 The \l{linguist-manager.html}{Release Manager} chapter is aimed
60 at the person with overall responsibility for the release of the
61 application. They will typically coordinate the work of the
62 software engineers and the translator. The chapter describes the
63 use of two tools. The \l{lupdate} tool is used to synchronize
64 source code and translations. The \l{lrelease} tool is used to
65 create runtime translation files for use by the released
68 The \l{linguist-translators.html}{Translators} chapter is for
69 translators. It describes the use of the \QL tool.
70 No computer knowledge beyond the ability to start a program and
71 use a text editor or word processor is required.
73 The \l{linguist-programmers.html}{Programmers} chapter is for Qt
74 programmers. It explains how to create Qt applications that are
75 able to use translated text. It also provides guidance on how to
76 help the translator identify the context in which phrases appear.
77 This chapter's three short tutorials cover everything the
78 programmer needs to do.
80 \section1 Overview of the Translation Process
82 Most of the text that must be translated in an application program
83 consists of either single words or short phrases. These typically
84 appear as window titles, menu items, pop-up help text (balloon help),
85 and labels to buttons, check boxes and radio buttons.
87 The phrases are entered into the source code by the programmer in
88 their native language using a simple but special syntax to identify
89 that the phrases require translation. The Qt tools provide context
90 information for each of the phrases to help the translator, and the
91 programmer is able to add additional context information to phrases
92 when necessary. The release manager generates a set of translation
93 files that are produced from the source files and passes these to the
94 translator. The translator opens the translation files using \QL,
95 enters their translations and saves the results back into
96 the translation files, which they pass back to the release manager.
97 The release manager then generates fast compact versions of these
98 translation files ready for use by the application. The tools are
99 designed to be used in repeated cycles as applications change and
100 evolve, preserving existing translations and making it easy to
101 identify which new translations are required. \QL also
102 provides a phrase book facility to help ensure consistent
103 translations across multiple applications and projects.
105 Translators and programmers must address a number of issues because
106 of the subtleties and complexities of human language:
110 \o A single phrase may need to be translated into several
111 different forms depending on context, e.g. \e open in English
112 might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen,
113 "open internet connection", in German.
115 \o Keyboard accelerators may need to be changed but without
116 introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt"
117 in Norwegian which doesn't contain a "Q". We cannot use a letter
118 that is already in use - unless we change several accelerators.
120 \o Phrases that contain variables, for example, "The 25 files
121 selected will take 63 seconds to process", where the two numbers
122 are inserted programmatically at runtime may need to be reworded
123 because in a different language the word order and therefore the
124 placement of the variables may have to change.
128 The Qt translation tools provide clear and simple solutions to these
134 \o \l{Qt Linguist Manual: Release Manager}{Release Manager}
135 \o \l{Qt Linguist Manual: Translators}{Translators}
136 \o \l{Qt Linguist Manual: Programmers}{Programmers}
137 \o \l{Qt Linguist Manual: TS File Format}{TS File Format}
140 \QL and \c lupdate are able to import and export XML Localization
141 Interchange File Format (XLIFF) files, making it possible to take
142 advantage of tools and translation services that work with this
143 format. See the \l{Qt Linguist Manual: Translators} {Translators}
144 section for more information on working with these files.
148 \row \o{1,2} \inlineimage wVista-Cert-border-small.png
149 \o \e{Qt Linguist 4.3 is Certified for Windows Vista}
151 \row \o Windows Vista and the Windows Vista Start button are
152 trademarks or registered trademarks of Microsoft Corporation in
153 the United States and/or other countries.
159 \page linguist-manager.html
160 \title Qt Linguist Manual: Release Manager
162 \contentspage {Qt Linguist Manual}{Contents}
163 \previouspage Qt Linguist Manual
164 \nextpage Qt Linguist Manual: Translators
169 Two tools are provided for the release manager, \l lupdate and \l
170 lrelease. These tools can process \l qmake project files, or operate
171 directly on the file system.
173 \section1 Qt Project Files
175 The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease}
176 {lrelease} is by specifing a \c .pro Qt project file. There must
177 be an entry in the \c TRANSLATIONS section of the project file for
178 each language that is additional to the native language. A typical
179 entry looks like this:
181 \snippet examples/linguist/arrowpad/arrowpad.pro 1
183 Using a locale within the translation file name is useful for
184 determining which language to load at runtime. This is explained
185 in the \l{linguist-programmers.html} {Programmers} chapter.
187 An example of a complete \c .pro file with four translation source
190 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0
191 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1
193 QTextCodec::setCodecForTr() makes it possible to choose a 8-bit
194 encoding for literal strings that appear within \c tr() calls.
195 This is useful for applications whose source language is, for
196 example, Chinese or Japanese. If no encoding is set, \c tr() uses
199 If you do use the QTextCodec::codecForTr() mechanism in your
200 application, \QL needs you to set the \c CODECFORTR
201 entry in the \c .pro file as well. For example:
203 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1
205 Also, if your compiler uses a different encoding for its runtime
206 system as for its source code and you want to use non-ASCII
207 characters in string literals, you will need to set the \c
208 CODECFORSRC. For example:
210 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2
212 Microsoft Visual Studio 2005 .NET appears to be the only compiler
213 for which this is necessary. However, if you want to write
214 portable code, we recommend that you avoid non-ASCII characters
215 in your source files. You can still specify non-ASCII characters
216 portably using escape sequences, for example:
218 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3
220 \target lupdate manual
223 Usage: \c {lupdate myproject.pro}
225 \l lupdate is a command line tool that finds the translatable
226 strings in the specified source, header and \e {Qt Designer}
227 interface files, and produces or updates \c .ts translation
228 files. The files to process and the files to update can be set at
229 the command line, or provided in a \c .pro file specified as an
230 command line argument. The produced translation files are given to
231 the translator who uses \QL to read the files and insert the
234 Companies that have their own translators in-house may find it
235 useful to run \l lupdate regularly, perhaps monthly, as the
236 application develops. This will lead to a fairly low volume of
237 translation work spread evenly over the life of the project and
238 will allow the translators to support a number of projects
241 Companies that hire in translators as required may prefer to run
242 \l lupdate only a few times in the application's life cycle, the
243 first time might be just before the first test phase. This will
244 provide the translator with a substantial single block of work and
245 any bugs that the translator detects may easily be included with
246 those found during the initial test phase. The second and any
247 subsequent \l lupdate runs would probably take place during the
250 The \c .ts file format is a simple human-readable XML format that
251 can be used with version control systems if required. \c lupdate
252 can also process Localization Interchange File Format (XLIFF)
253 format files; file in this format typically have file names that
254 end with the \c .xlf suffix.
256 Pass the \c -help option to \c lupdate to obtain the list of
259 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4
261 \QL is also able to import and export XLIFF files. See the
262 \l{Qt Linguist Manual: Translators}{Translators} section for more
267 Usage: \c {lrelease myproject.pro}
269 \l lrelease is a command line tool that produces \c .qm files out
270 of \c .ts files. The \c .qm file format is a compact binary format
271 that is used by the localized application. It provides extremely
272 fast lookups for translations. The \c .ts files \l lrelease
273 processes can be specified at the command line, or given
274 indirectly by a Qt \c .pro project file.
276 This tool is run whenever a release of the application is to be
277 made, from initial test version through to final release
278 version. If the \c .qm files are not created, e.g. because an
279 alpha release is required before any translation has been
280 undertaken, the application will run perfectly well using the text
281 the programmers placed in the source files. Once the \c .qm files
282 are available the application will detect them and use them
285 Note that lrelease will only incorporate translations that are
286 marked as "finished". Otherwise the original text will be used
289 Pass the \c -help option to \c lrelease to obtain the list of
292 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5
294 \section1 Missing Translations
296 Both \l lupdate and \l lrelease may be used with \c .ts
297 translation source files which are incomplete. Missing
298 translations will be replaced with the native language phrases at
303 \page linguist-translators.html
304 \title Qt Linguist Manual: Translators
306 \contentspage {Qt Linguist Manual}{Contents}
307 \previouspage Qt Linguist Manual: Release Manager
308 \nextpage Qt Linguist Manual: Programmers
314 \section1 The One Minute Guide to Using Qt Linguist
316 \QL is a tool for adding translations to Qt applications. Run \QL
317 from the taskbar menu, or by double clicking the desktop icon, or
318 by entering the command \c {linguist} at the command line. Once
319 \QL has started, choose \menu{File|Open} from the \l{menubar}
320 {menu bar} and select a translation source (\c{.ts} file) to
321 load. If you don't have a \c{.ts} file, see the \l {Qt Linguist
322 Manual: Release Manager} {release manager manual} to learn how to
325 The \QL main window is divided into several, dockable subwindows
326 arranged around a central \l{The Translation Area} {translation
327 area}. The \l{Context Window} {context list} is normally shown
328 on the left, and the \l{Sources and Forms Window} {source code},
329 \l{Strings Window} {string list}, and either the \l{Phrases and
330 Guesses Window} {prhrases and guesses}, or the \l{Warnings Window}
331 {warnings} are shown above and below the \l{The Translation Area}
334 With a translation file loaded, select a context from the
335 \l{Context Window} {context list} on the left. Selecting a context
336 loads the translatable strings found in that context into the
337 \l{Strings Window} {string list}. Selecting one of the strings
338 copies that string as the \key{Source text} in the \l{The
339 Translation Area} {translation area}. Click in the text entry
340 widget below the copied string and type your translation for that
341 string. To accept the translation, either press the green
342 \key{tick mark} button on the toolbar, or click the icon to the
343 left of the selected source string in the string list. Repeat this
344 process until all strings in the string list are marked with
345 \inlineimage linguist-check-on.png
347 \inlineimage linguist-check-warning.png
348 . Then select the next context and continue.
350 Translation options are shown in the \l{Phrases and Guesses
351 Window} {phrases and guesses window}. If the phrases and guesses
352 window is not visible, click the \key{Phrases and guesses} tab at
353 the bottom of the main window. The phrases and guesses window
354 shows possible translations for the current string. These
355 translation "guesses" have been read from phrase books
356 (\menu{Phrases|Open Phrase Book...}). The current string's
357 current translation is also shown here. To select a guess, double
358 click it in the prases and guesses window or use the keyboard
359 shortcut shown to the right of the guess.
361 \QL can automatically check whether your translation strings pass
362 a list of \l{Validation Tests} {validation tests}. Validation test
363 failures are shown in the \l{Warnings Window} {warnings window}.
364 If the warnings window is not visible, click the \key{Warnings}
365 tab at the bottom of the main window.
367 Finally, if the source code for the contexts is accessible, the
368 \l{Sources and Forms Window} {source code window} shows the
369 context where the current string is used. If the source code
370 window is not visible, click the \key{Sources and Forms} tab at
371 the bottom of the main window.
373 At the end of the session choose \menu{File|Save} from the menu
374 bar and then \menu{File|Exit} to quit.
376 \section1 The Qt Linguist Window
378 \image linguist-linguist.png "Linguist UI Snapshot"
380 This \QL main window is divided into dockable subwindows arranged
381 around a central \l{The Translation Area} {translation area}. The
382 subwindows are: \l{Context Window} {Context}, \l{Sources and Forms
383 Window} {Sources and Forms}, \l{Strings Window} {Strings},
384 \l{Phrases and Guesses Window} {Phrases and guesses}, and
385 \l{Warnings Window} {Warnings} (hidden in the UI snapsot). The
386 translation area is always visible, but the dockable subwindows
387 can be activated or deactivated in the \menu{View|Views} menu, and
388 dragged around by their title bars and dropped in the translation
389 area or even outside the main window.
391 \section2 Context Window
393 The context window normally appears on the left side of the main
394 window. It lists the contexts in which strings to be translated
395 appear. The column labeled \e{Context} lists the context names in
396 alphabetical order. Each context is the name of a subclass of
397 QObject. There can also be a context for QObject itself, which
398 contains strings passed to the static function QObject::tr().
399 There can also be an \e{<unnamed context>}, which contains strings
400 that aren't in a subclass of QObject.
402 To the left of the \e{Context} column is a column labeled
403 \inlineimage linguist-check-obsolete.png
404 . This column uses the following list of icons to summarize the
405 current translation state for each context:
409 \o \inlineimage linguist-check-on.png
410 All strings in the context have been translated, and all the
411 translations passed the \l{Validation Tests} {validation tests}.
413 \o \inlineimage linguist-check-warning.png
414 All strings in the context have been translated or marked as
415 translated, but at least one translation failed the \l{Validation
416 Tests} {validation tests}.
418 \o \inlineimage linguist-check-off.png
419 At least one string in the context has not been translated or is
420 not marked as translated.
422 \o \inlineimage linguist-check-obsolete.png
423 None of the translated strings still appears in the context. This
424 usually means the context itself no longer exists in the
429 To the right of the \e{Context} column is the \e{Items} column.
430 Each entry in the \e{Items} column is a pair of numbers separated
431 by a slash ("/"). The number to the right of the slash is the
432 number of translatable strings in the context. The number to the
433 left of the slash is the number of those strings that currently
434 have translations. i.e., if the numbers are equal, all the
435 translatable strings in the context have translations.
437 In the UI snapshot above, the \bold{MessageEditor} context is
438 selected. Its \e{Items} entry shows \bold{18/18}, which means it
439 has 18 translatable strings and all 18 strings currently have
440 translations. However, the context has been marked with the
441 \inlineimage linguist-check-warning.png
442 icon, which means that at least one of the current translations
443 failed a \l{Validation Tests} {validation test}. In the
444 \l{Strings Window} {strings window} to the right, we see that one
445 of the strings is indeed marked with the
446 \inlineimage linguist-check-warning.png
449 The context window is a dockable window. It can be dragged to
450 another position in the main window, or dragged out of the main
451 window to be a separate window. If you move the context window,
452 \QL remembers the new position and puts the context window there
453 whenever you start the program. If the context window has been
454 closed, it can be restored by pressing \key{F6}.
456 \section2 Strings Window
458 The strings window normally appears on the right in the main
459 window, above the \l{The Translation Area} {translation area}. Its
460 \e{Source text} column lists all the translatable strings found in
461 the current context. Selecting a string makes that string the
462 current string in the \l{The Translation Area} {translation area}.
464 To the left of the \e{Source text} column is a column labeled
465 \inlineimage linguist-check-obsolete.png
466 . This column is similar to the one in the \l{Context Window}
467 {context window}, but here you can click on the icon to change the
468 translation acceptance state for each string in the list. A tick
469 mark, green or yellow, means the string has been translated and
470 the user has accepted the translation. A question mark means
471 either that the user has not accepted the string's translation or
472 that the string doesn't have a translation. The table below
473 explains the acceptance states and their icons:
475 \target String Translation States
485 \o \inlineimage linguist-check-on.png
486 \o The source string has a translation (possibly empty); the user
487 has accepted the translation, and the translation passes all the
488 \l{Validation Tests} {validation tests}. If the translation is
489 empty, the user has chosen to leave it empty. Click the icon to
490 revoke acceptance of the translation and decrement the number of
491 accepted translations in the \e{Items} column of the \l{Context
492 Window} {context list} by 1. The state is reset to
493 \inlineimage linguist-check-off.png
494 if the string has a translation, or to
495 \inlineimage linguist-check-empty.png
496 if the string's translation is empty. If \c{lupdate} changes the
497 contents of a string, its acceptance state is automatically reset
498 to \inlineimage linguist-check-off.png
503 \o \inlineimage linguist-check-warning.png
504 \o The user has accepted the translation, but the translation does
505 not pass all the \l{Validation Tests} {validation tests}. The
506 validation test failures are shown in the \l{Warnings Window}
507 {warnings window}. Click the icon to revoke acceptance of the
508 translation. The state is reset to \inlineimage linguist-danger.png
509 , and the number of accepted translations in the \e{Items} column
510 of the \l{Context Window} {context list} is decremented by 1.
514 \o \inlineimage linguist-check-off.png
515 \o The string has a non-empty translation that passes all the
516 \l{Validation Tests} {validation tests}, but the user has not yet
517 accepted the translation. Click the icon or press \key{Ctrl+Enter}
518 to accept the translation. The state is reset to
519 \inlineimage linguist-check-on.png
520 , and the number of accepted translations in the \e{Items} column
521 of the \l{Context Window} {context list} is incremented by 1.
525 \o \inlineimage linguist-check-empty.png
526 \o The string does not have a translation. Click the icon to
527 accpet the empty translation anyway. The state is reset to
528 \inlineimage linguist-check-on.png
529 , and the number of accepted translations in the \e{Items} column
530 of the \l{Context Window} {context list} is incremented by 1.
533 \o Validation Failures
534 \o \inlineimage linguist-danger.png
535 \o The string has a translation, but the translation does not
536 pass all the \l{Validation Tests} {validation tests}. Validation
537 test failures are shown in the \l{Warnings Window} {warnings}
538 window. Click on the icon or press \key{Ctrl+Return} to accept
539 the translation even with validation failures. The state is
540 reset to \inlineimage linguist-check-warning.png
541 . We recommended editing the translation to fix the causes of
542 the validation failures. The state will reset automatically to
543 \inlineimage linguist-check-off.png
544 , when all the failures have been fixed.
548 \o \inlineimage linguist-check-obsolete.png
549 \o The string is obsolete. It is no longer used in the context.
550 See the \l{Qt Linguist Manual: Release Manager} {Release Manager}
551 for instructions on how to remove obsolete messages from the file.
555 The string list is a dockable subwindow. If it has been closed,
556 restored it by pressing \key{F7}.
558 \section2 The Translation Area
560 The translation area is in the middle of the main window, to the
561 right of the \l{Context Window} {context list}. It doesn't have a
562 title bar, so you can't drag it around. Instead, you drag and drop
563 the other subwindows to arrange them around the translation area.
564 The string currently selected in the \l{Strings Window} {string
565 list} appears at the top of the translation area, under the label
566 \menu{Source text}. Note that all blanks in the source text have
567 been replaced by "." so the translator can see the spacing
568 required within the text.
570 If the developer provides a \l{QObject::tr()} {disambiguating
571 comment}, it will appear below the source text area, under the
572 label \menu{Developer comments}.
574 Below the source text and optional developer comments are two text
575 entry widgets for the translator, one for entering the translation
576 of the current string, and one for the translator to enter an
577 optional comment to be read by other translators.
579 When \l{Translating Multiple Languages Simultaneously} {multiple
580 languages} are being translated, this sequence of fields is
581 repeated for each language. See aso \l {Changing the Target
584 \section2 Phrases and Guesses Window
586 If the current string in the \l{Strings Window} {string list}
587 appears in one or more of the \l{Phrase Books} {phrase books}
588 that have been loaded, the current string and its phrase book
589 translation(s) will be listed in this window. If the current
590 string is the same as, or similar to, another string that has
591 already been translated, that other string and its translation
592 will also be listed in this window.
594 To use a translation from the Phrases and Guesses Window, you can
595 double click the translation, and it will be copied into the
596 translation area, or you can use the translation's \e{Guess}
597 hotkey on the right. You can also press \key{F10} to move the
598 focus to the Phrases and Guesses Window, then use the up and down
599 arrow keys to find the desired translation, and and then press
600 \key{Enter} to copy it to the translation area. If you decide
601 that you don't want to copy a phrase after all, press \key{Esc} to
602 return the focus to the translation area.
604 The Phrases and Guesses Window is a dockable window. If it has
605 been closed, it can be made visible by pressing the \e{Phrases and
606 guesses} tab at the bottom of the window, or by pressing
609 \section2 Sources and Forms Window
611 If the source files containing the translatable strings are
612 available to \QL, this window shows the source context of the
613 current string in the \l{Strings Window} {string list}. The source
614 code line containing the current string should be shown and
615 highlighted. If the file containing the source string is not
616 found, the expected absolute file path is shown.
618 If the source context shows the wrong source line, it probably
619 means the translation file is out of sync with the source files.
620 To re-sync the translation file with the source files, see the
621 \l{lupdate manual} {lupdate manual}.
623 The Sources and Forms window is a dockable window. If it has been
624 closed, it can be made visible again by pressing the \e{Sources
625 and Forms} tab at the bottom of the window, or by pressing
628 \section2 Warnings Window
630 If the translation you enter for the current string fails any of
631 the active \l{Validation Tests} {validation tests}, the failures
632 are listed in the warnings window. The first of these failure
633 messages is also shown in the status bar at the bottom of the main
634 window. Note that only \e{active} validation tests are
635 reported. To see which validation tests are currently active, or
636 to activate or deactivate tests, use the \menu{Validation} menu
637 from the \l{menubar}{menu bar}.
639 The Warnings window is a dockable window. If it has been closed,
640 it can be made visible by pressing the \e{Warnings} tab at the
641 bottom of the window, or by pressing \key{F8}.
643 \target multiple languages
644 \section2 Translating Multiple Languages Simultaneously
646 Qt Linguist can now load and edit multiple translation files
647 simultaneously. One use for this is the case where you know two
648 languages better than you know English (Polish and Japanese, say),
649 and you are given an application's Polish translation file and
650 asked to update the application's Japanese translation file. You
651 are more comfortable translating Polish to Japanese than you are
652 translating English to Japanese.
654 Below is the UI snapshot shown earlier, but this time with both
655 \e{Polish} and \e{Japanese} translation files loaded.
657 \image linguist-linguist_2.png
659 The first thing to notice is that the \l{The Translation Area}
660 {translation area} has text editing areas for both Polish and
661 Japanese, and these are color-coded for easier separation.
662 Second, the \l{Context Window} and the \l{Strings Window} both
663 have two clomuns labeled \inlineimage linguist-check-obsolete.png
664 instead of one, and although it may be hard to tell, these columns
665 are also color-coded with the same colors. The left-most column in
666 either case applies to the top-most language area (Polish above)
667 in the \l{The Translation Area} {translation area}, and the
668 right-most column applies to the bottom language area.
670 The \e{Items} column in the \l{Context Window} combines the values
671 for both languages. The best way to see this is to look at the
672 value for the \bold{MessageEditor} context, which is the one
673 selected in the snapshot shown above. Recall that in the first UI
674 snapshot (Polish only), the numbers for this context were
675 \e{18/18}, meaning 18 translatable strings had been found in the
676 context, and all 18 strings had accepted translations. In the UI
677 snapshot above, the numbers for the \bold{MessageEditor} context
678 are now \e{1/18}, meaning that both languages have 18 translatable
679 strings for that context, but for Japanese, only 1 of the 18
680 strings has an accepted translation. The
681 \inlineimage linguist-check-off.png
682 icon in the Japanese column means that at least one string in the
683 context doesn't have an accepted Japanese translation yet. In fact,
684 17 of the 18 strings don't have accepted Japanese translations yet.
685 We will see \e{18/18} in the \e{Items} column when all 18 strings
686 have accepted translations for all the loaded translation files,
687 e.g., both Polish and Japanese in the snapshot.
689 \section1 Common Tasks
691 \section2 Leaving a Translation for Later
693 If you wish to leave a translation press \key{Ctrl+L} (Next
694 Unfinished) to move to the next unfinished translation. To move to
695 the next translation (whether finished or unfinished) press
696 \key{Shift+Ctrl+L}. You can also navigate using the Translation
697 menu. If you want to go to a different context entirely, click the
698 context you want to work on in the Context list, then click the
699 source text in the \l{Strings Window} {string list}.
701 \section2 Phrases That Require Multiple Translations Depending on Context
703 The same phrase may occur in two or more contexts without conflict. Once
704 a phrase has been translated in one context, \QL notes
705 that the translation has been made and when the translator reaches a
706 later occurrence of the same phrase \QL will provide
707 the previous translation as a possible translation candidate in the
708 \l{Phrases and Guesses Window}.
710 If a phrase occurs more than once in a particular context it will
711 only be shown once in \QL's \l{Context Window} {context list} and
712 the translation will be applied to every occurrence within the
713 context. If the same phrase needs to be translated differently
714 within the same context the programmer must provide a
715 distinguishing comment for each of the phrases concerned. If such
716 comments are used the duplicate phrases will appear in the
717 \l{Context Window} {context list}. The programmers comments will
718 appear in the \l{The Translation Area} {translation area} on a
719 light blue background.
721 \section2 Changing Keyboard Accelerators
723 A keyboard accelerator is a key combination that, when pressed,
724 causes an application to perform an action. There are two kinds of
725 keyboard accelerators: Alt key and Ctrl key accelerators.
727 \section3 Alt Key Accellerators
729 Alt key accelerators are used in menu selection and on buttons.
730 The underlined character in a menu item or button label signifies
731 that pressing the Alt key with the underlined character will
732 perform the same action as clicking the menu item or pressing the
733 button. For example, most applications have a \e{File} menu with
734 the "F" in the word "File" underlined. In these applications the
735 \e{File} menu can be invoked either by clicking the word "File" on
736 the menu bar or by pressing \e{Alt+F}. To identify an accelerator
737 key in the translation text ("File") precede it with an ampersand,
738 e.g. \e{\&File}. If a string to be translated has an ampersand in
739 it, then the translation for that string should also have an
740 ampersand in it, preferably in front of the same character.
742 The meaning of an Alt key accelerator can be determined from the
743 phrase in which the ampersand is embedded. The translator can
744 change the character part of the Alt key accelerator, if the
745 translated phrase does not contain the same character or if that
746 character has already been used in the translation of some other
747 Alt key accelerator. Conflicts with other Alt key accelerators
748 must be avoided within a context. Note that some Alt key
749 accelerators, usually those on the menu bar, may apply in other
752 \section3 Ctrl Key Accelerators
754 Ctrl key accelerators can exist independently of any visual
755 control. They are often used to invoke actions in menus that would
756 otherwise require multiple keystrokes or mouse clicks. They may
757 also be used to perform actions that do not appear in any menu or
758 on any button. For example, most applications that have a \e{File}
759 menu have a \e{New} submenu item in the \e{File} menu. The \e{New}
760 item might appear as "\underline{N}ew Ctrl+N" in the \e{File}
761 menu, meaning the \e{New} menu can be invoked by simply pressing
762 \key{Ctrl+N}, instead of either clicking \e{File} with the mouse
763 and then clicking \e{New} with the mouse, or by entering \e{Alt+F}
766 Each Ctrl key accelerator is shown in the \l{Strings Window}
767 {string list} as a separte string, e.g. \key{Ctrl+Enter}. Since
768 the string doesn't have a context to give it meaning, e.g. like
769 the context of the phrase in which an Alt key accelerator appears,
770 the translator must rely on the UI developer to include a
771 \l{QObject::tr()} {disambiguation comment} to explain the action
772 the Ctrl key accelerator is meant to perform. This disambiguating
773 comment (if provided by the developer) will appear under
774 \e{Developer comments} in the \l{The Translation Area}
775 {translation area} under the \e{Source text} area.
777 Ideally Ctrl key accelerators are translated simply by copying
778 them directly using \e {Copy from source text} in the
779 \menu{Translation} menu. However, in some cases the character will
780 not make sense in the target language, and it must be
781 changed. Whichever character (alpha or digit) is chosen, the
782 translation must be in the form "Ctrl+" followed by the upper case
783 character. \e{Qt} will automatically display the correct name at
784 runtime. As with Alt key accelerators, if the translator changes
785 the character, the new character must not conflict with any other
786 Ctrl key accelerator.
788 \warning Do not translate the "Alt", "Ctrl" or "Shift" parts of
789 the accelerators. \e{Qt} relies on these strings being there. For
790 supported languages, \e {Qt} automatically translates these
793 \section2 Handling Numbered Arguments
795 Some phrases contain numbered arguments. A numbered argument is a
796 placeholder that will be replaced with text at runtime. A numbered
797 argument appears in a source string as a percent sign followed by
798 a digit. Consider an example: \c{After processing file %1, file %2
799 is next in line}. In this string to be translated, \c{%1} and
800 \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%2} will
801 be replaced with the first and next file names respectively. The
802 same numbered arguments must appear in the translation, but not
803 necessarily in the same order. A German translation of the string
804 might reverse the phrases, e.g. \c{Datei %2 wird bearbeitet, wenn
805 Datei %1 fertig ist}. Both numbered arguments appear in the
806 translation, but in the reverse order. \c{%i} will always be
807 replaced by the same text in the translation stringss, regardless
808 of where argument \e{i} appears in the argument sequence in the
811 \section2 Reusing Translations
813 If the translated text is similar to the source text, choose the
814 \e {Copy from source text} entry in the \menu Translation menu (press
815 \key{Ctrl+B}) which will copy the source text into the
816 \l{The Translation Area} {translation area}.
818 \QL automatically lists possible translations from any open
819 \l{Phrase Books} {phrase books} in the \l{Phrases and Guesses
820 Window}, as well as similar or identical phrases that have already
823 \section2 Changing the Target Locale
825 \QL displays the target language in the \l{The Translation Area}
826 {translation area}, and adapts the number of input fields for
827 plural forms accordingly. If not explicitly set, \QL guesses the
828 target language and country by evaluating the translation source
829 file name: E.g. \c app_de.ts sets the target language to German,
830 and \c app_de_ch.ts sets the target language to German and the
831 target country to Switzerland (this also helps loading
832 translations for the current locale automatically; see
833 \l{linguist-programmers.html}{Programmers Manual} for details).
834 If your files do not follow this convention, you can also set the
835 locale information explicitly using \e {Translation File Settings}
836 in the \menu Edit menu.
838 \image linguist-translationfilesettings.png
840 \section1 Phrase Books
842 A \QL phrase book is a set of source phrases, target
843 (translated) phrases, and optional definitions. Typically one phrase book
844 will be created per language and family of applications. Phrase books
845 are used to provide a common set of translations to help ensure consistency.
846 They can also be used to avoid duplication of effort since the translations
847 for a family of applications can be produced once in the phrase book.
848 If the translator reaches an untranslated phrase that is the same as a
849 source phrase in a phrase book, \QL will show the
850 phrase book entry in the \l {Phrases and Guesses Window}.
852 \section2 Creating and Editing Phrase Books
854 \image linguist-phrasebookdialog.png
856 Before a phrase book can be edited it must be created or, if it already
857 exists, opened. Create a new phrase book by selecting
858 \menu{Phrase|New Phrase Book} from the menu bar. You must enter a
859 filename and may change the location of the file if you wish. A newly
860 created phrase book is automatically opened. Open an existing phrase
861 book by choosing \menu{Phrase|Open Phrase Book} from the menu bar.
863 The phrase book contents can be displayed and changed by selecting
864 \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you
865 want to work on. This will pop up the Phrase Book Dialog as shown
866 in the image above. To add a new phrase click the \gui{New Phrase}
867 button (or press Alt+N) and type in a new source phrase. Press Tab and
868 type in the translation. Optionally press Tab and enter a definition --
869 this is useful to distinguish different translations of the same source
870 phrase. This process may be repeated as often as necessary. You can delete
871 a phrase by selecting it in the phrases list and clicking
872 Remove Phrase. Click the \gui Close button (press Esc) once you've finished
873 adding (and removing) phrases.
875 \section2 Shortcuts for Editing Phrase Books
877 You can also create a new phrase book entry directly out of the translation you
878 are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing
879 \key{Ctrl+T} will add the source text and the content of the first translation
880 field to the current phrase book. If multiple phrase books are loaded,
881 you have to specify the phrase book to add the entry to in a dialogue.
882 If you detect an error in a phrase book entry that is shown in the
883 \l{Phrases and Guesses Window}, you can also edit it in place by right
884 clicking on the entry, and selecting \menu{Edit}. After fixing the error
885 press \key{Return} to leave the editing mode.
887 \section2 Batch Translation
889 \image linguist-batchtranslation.png
891 Use the batch translation feature of \QL to automatically
892 translate source texts that are also in a phrase book. Selecting
893 \menu{Tools|Batch Translation} will show you the batch translation dialog,
894 which let you configure which phrase books to use in what order during the
895 batch translation process. Furthermore you can set whether only entries
896 with no present translation should be considered, and whether batch translated
897 entries should be set to finished (see also \l {String Translation States}).
899 \section1 Validation Tests
901 \QL provides four kinds of validation tests for translations.
904 \o \e {Accelerator validation} detects translated phrases
905 that do not have an ampersand when the source phrase does and vice
907 \o \e {Punctuation validation} detects differences in the
908 terminating punctuation between source and translated phrases when this
909 may be significant, e.g. warns if the source phrase ends with an
910 ellipsis, exclamation mark or question mark, and the translated phrase
911 doesn't and vice versa.
912 \o \e {Phrases validation} detects source phrases that are
913 also in the phrase book but whose translation differs from that given in
915 \o \e {Place marker validation} detects whether the same variables
916 (like \c %1, \c %2) are used both in the source text and in the translation.
919 Validation may be switched on or off from the menu bar's
920 Validation item or using the toolbar buttons. Unfinished phrases
921 that fail validation are marked with an exclamation mark in the
922 source text pane. Finished phrases will get a yellow tick
923 instead. If you switch validation off and then switch it on later,
924 \QL will recheck all phrases and mark any that fail
925 validation. See also \l{String Translation States}.
927 \section1 Form Preview
929 \image linguist-previewtool.png
931 Forms created by \e{Qt Designer} are stored in special \c .ui files.
932 \QL can make use of these \c .ui files to show the translations
933 done so far on the form itself. This of course requires access to the \c .ui
934 files during the translation process. Activate
935 \menu{Tools|Open/Refresh Form Preview} to open the window shown above.
936 The list of \c .ui files \QL has detected are displayed in the Forms
937 List on the left hand. If the path to the files has changed, you can load
938 the files manually via \menu{File|Open Form...}. Double-click on an entry
939 in the Forms List to display the Form File. Select \e{<No Translation>} from
940 the toolbar to display the untranslated form.
942 \section1 Qt Linguist Reference
947 \QL makes use of four kinds of files:
950 \o \c .ts \e {translation source files} \BR are human-readable XML
951 files containing source phrases and their translations. These files are
952 usually created and updated by \l lupdate and are specific to an
954 \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere
955 to the international XML Localization Interchange File Format. \QL
956 can be used to edit XLIFF files generated by other programs. For standard
957 Qt projects, however, only the \c .ts file format is used.
958 \o \c .qm \e {Qt message files} \BR are binary files that contain
959 translations used by an application at runtime. These files are
960 generated by \l lrelease, but can also be generated by \QL.
961 \o \c .qph \e {Qt phrase book files} \BR are human-readable XML
962 files containing standard phrases and their translations. These files
963 are created and updated by \QL and may be used by any
964 number of projects and applications.
968 \section2 The Menu Bar
970 \image linguist-menubar.png
975 \o \gui {Open... Ctrl+O} \BR pops up an open file dialog from which a
976 translation source \c .ts or \c .xlf file can be chosen.
977 \o \gui {Recently opened files} \BR shows the \c .ts files that
978 have been opened recently, click one to open it.
979 \o \gui {Save Ctrl+S} \BR saves the current translation source file.
980 \o \gui {Save As...} \BR pops up a save as file dialog so that the
981 current translation source file may be saved with a different
982 name, format and/or put in a different location.
983 \o \gui {Release} \BR create a Qt message \c .qm file with the same base
984 name as the current translation source file. The release manager's
985 command line tool \l lrelease performs the same function on
986 \e all of an application's translation source files.
987 \o \gui {Release As...} \BR pops up a save as file dialog. The
988 filename entered will be a Qt message \c .qm file of the translation
989 based on the current translation source file. The release manager's
990 command line tool \l lrelease performs the same function on
991 \e all of an application's translation source files.
992 \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click
993 OK the translation source and the translations will be printed.
994 \o \gui {Exit Ctrl+Q} \BR closes \QL.
999 \o \gui {Undo Ctrl+Z} \BR undoes the last editing action in the
1001 \o \gui {Redo Ctrl+Y} \BR redoes the last editing action in the
1003 \o \gui {Cut Ctrl+X} \BR deletes any highlighted text in the
1004 translation pane and saves a copy to the clipboard.
1005 \o \gui {Copy Ctrl+C} \BR copies the highlighted text in the
1006 translation pane to the clipboard.
1007 \o \gui {Paste Ctrl+V} \BR pastes the clipboard text into the
1010 \o \gui {Delete} \BR deletes the highlighted text in the
1013 \o \gui {Select All Ctrl+A} \BR selects all the text in the
1014 translation pane ready for copying or deleting.
1015 \o \gui {Find... Ctrl+F} \BR pops up the
1016 Find dialog. When the dialog pops up
1017 enter the text to be found and click the \gui {Find Next} button.
1018 Source phrases, translations and comments may be searched.
1019 \o \gui {Find Next F3} \BR finds the next occurrence of the text that
1020 was last entered in the Find dialog.
1021 \o \gui {Search and Translate...} \BR pops up the Search and
1022 Replace Dialog. Use this dialog to translate the same text in multiple items.
1023 \o \gui {Translation File Settings...} \BR let you configure the target
1024 language and the country/region of a translation source file.
1027 \o \gui {Translation}
1029 \o \gui {Prev Unfinished Ctrl+K} \BR moves to the nearest previous
1030 unfinished source phrase (unfinished means untranslated or
1031 translated but failed validation).
1032 \o \gui {Next Unfinished Ctrl+L} \BR moves to the next unfinished source
1034 \o \gui {Prev Shift+Ctrl+K} \BR moves to the previous source phrase.
1035 \o \gui {Next Shift+Ctrl+L} \BR moves to the next source phrase.
1036 \o \gui {Done \& Next Ctrl+Enter} \BR mark this phrase as 'done'
1037 (translated) and move to the next unfinished source phrase.
1038 \o \gui {Copy from source text Ctrl+B} \BR copies the source text into
1042 \o \gui {Validation} (See \l{Validation Tests})
1044 \o \gui {Accelerators} \BR toggles validation on or off for Alt
1046 \o \gui {Ending Punctuation} \BR switches validation on or off
1047 for phrase ending punctuation, e.g. ellipsis, exclamation mark,
1049 \o \gui {Phrase Matches} \BR sets validation on or off for
1050 matching against translations that are in the current phrase book.
1051 \o \gui {Place Marker Matches} \BR sets validation on or off for
1052 the use of the same place markers in the source and translation.
1055 \o \gui {Phrases} (See the section \l {Phrase Books} for details.)
1058 \o \gui {New Phrase Book... Ctrl+N} \BR pops up a save as file
1059 dialog. You must enter a filename to be used for the phrase
1060 book and save the file. Once saved you should open the phrase
1061 book to begin using it.
1063 \o \gui {Open Phrase Book... Ctrl+H} \BR pops up an open file
1064 dialog. Find and choose a phrase book to open.
1066 \o \gui {Close Phrase Book} \BR displays the list of phrase
1067 books currently opened. Clicking on one of the items will
1068 close the phrase book. If the phrase book has been modified, a
1069 dialog box asks whether \QL should save the changes.
1071 \o \gui {Edit Phrase Book...} \BR displays the list of phrase
1072 books currently opened. Clicking on one of the items will open
1073 the \l{Creating and Editing Phrase Books}{Phrase Book Dialog}
1074 where you can add, edit or delete phrases.
1076 \o \gui {Print Phrase Book...} \BR displays the list of phrase
1077 books currently opened. Clicking on one of the items pops up a
1078 print dialog. If you click OK the phrase book will be
1081 \o \gui {Add to Phrase Book Ctrl+T} \BR Adds the source text
1082 and translation currently shown in the \l{The Translation
1083 Area} {translation area} to a phrase book. If multiple phrase
1084 books are loaded, a dialog box let you specify select one.
1091 \o \gui {Batch Translation...} \BR Opens a \l{Batch
1092 Translation}{dialog} which let you automatically insert
1093 translations for source texts which are in a phrase book.
1095 \o \gui {Open/Refresh Form Preview F3} \BR Opens the \l{Form
1096 Preview}. This window let you instantly see translations for
1097 forms created with \QD. \endlist
1102 \o \gui {Revert Sorting} \BR puts the items in the \l{Context
1103 Window} {context list} and in the \l{Strings Window} {string
1104 list} into their original order.
1106 \o \gui {Display Guesses} \BR turns the display of phrases and
1109 \o \gui {Statistics} \BR toggles the visibility of the
1112 \o \gui {Views} \BR toggles the visibility of the \l{Context
1113 Window}, \l{Strings Window}, \l{Phrases and Guesses Window},
1114 \l{Warnings Window}, or \l{Sources and Forms Window}.
1116 \o \gui {Toolbars} \BR toggles the visibility of the different
1123 \o \gui {Manual F1} \BR opens this manual.
1124 \o \gui {About Qt Linguist} \BR Shows information about \QL.
1125 \o \gui {About Qt} \BR Shows information about \e{Qt}.
1126 \o \gui {What's This? Shift+F1} \BR Click on one item in the main window
1127 to get additional information about it.
1132 \section2 The Toolbar
1134 \image linguist-toolbar.png
1137 \o \inlineimage linguist-fileopen.png
1139 Pops up the open file dialog to open a new translation source \c .ts
1142 \o \inlineimage linguist-filesave.png
1144 Saves the current translation source \c .ts file.
1146 \o \inlineimage linguist-fileprint.png
1148 Prints the current translation source \c .ts file.
1150 \o \inlineimage linguist-phrasebookopen.png
1152 Pops up the file open dialog to open a new phrase book \c .qph file.
1154 \o \inlineimage linguist-editundo.png
1156 Undoes the last editing action in the translation pane.
1158 \o \inlineimage linguist-editredo.png
1160 Redoes the last editing action in the translation pane.
1162 \o \inlineimage linguist-editcut.png
1164 Deletes any highlighted text in the translation pane and save a copy to
1167 \o \inlineimage linguist-editcopy.png
1169 Copies the highlighted text in the translation pane to the clipboard.
1171 \o \inlineimage linguist-editpaste.png
1173 Pastes the clipboard text into the translation pane.
1175 \o \inlineimage linguist-editfind.png
1177 Pops up the Find dialog .
1179 \o \inlineimage linguist-prev.png
1181 Moves to the previous source phrase.
1183 \o \inlineimage linguist-next.png
1185 Moves to the next source phrase.
1187 \o \inlineimage linguist-prevunfinished.png
1189 Moves to the previous unfinished source phrase.
1191 \o \inlineimage linguist-nextunfinished.png
1193 Moves to the next unfinished source phrase.
1195 \o \inlineimage linguist-doneandnext.png
1197 Marks the phrase as 'done' (translated) and move to the next
1198 unfinished source phrase.
1200 \o \inlineimage linguist-validateaccelerators.png
1202 Toggles accelerator validation on and off.
1204 \o \inlineimage linguist-validatepunctuation.png
1206 Toggles phrase ending punctuation validation on and off.
1208 \o \inlineimage linguist-validatephrases.png
1210 Toggles phrase book validation on or off.
1212 \o \inlineimage linguist-validateplacemarkers.png
1214 Toggles place marker validation on or off.
1221 \page linguist-programmers.html
1222 \title Qt Linguist Manual: Programmers
1224 \contentspage {Qt Linguist Manual}{Contents}
1225 \previouspage Qt Linguist Manual: Translators
1226 \nextpage Qt Linguist Manual: TS File Format
1228 Support for multiple languages is extremely simple in Qt
1229 applications, and adds little overhead to the programmer's workload.
1231 Qt minimizes the performance cost of using translations by
1232 translating the phrases for each window as they are created. In most
1233 applications the main window is created just once. Dialogs are often
1234 created once and then shown and hidden as required. Once the initial
1235 translation has taken place there is no further runtime overhead for
1236 the translated windows. Only those windows that are created,
1237 destroyed and subsequently created will have a translation
1240 Creating applications that can switch language at runtime is possible
1241 with Qt, but requires a certain amount of programmer intervention and
1242 will of course incur some runtime performance cost.
1244 \section1 Making the Application Translation-Aware
1246 Programmers should make their application look for and load the
1247 appropriate translation file and mark user-visible text and Ctrl
1248 keyboard accelerators as targets for translation.
1250 Each piece of text that requires translating requires context to help
1251 the translator identify where in the program the text occurs. In the
1252 case of multiple identical texts that require different translations,
1253 the translator also requires some information to disambiguate the
1254 source texts. Marking text for translation will automatically cause
1255 the class name to be used as basic context information. In some cases
1256 the programmer may be required to add additional information to help
1259 \section2 Creating Translation Files
1261 Translation files consist of all the user-visible text and Ctrl key
1262 accelerators in an application and translations of that text.
1263 Translation files are created as follows:
1266 \o Run \l lupdate initially to generate the first set of \c .ts
1267 translation source files with all the user-visible text but no
1269 \o The \c .ts files are given to the translator who adds translations
1270 using \QL. \QL takes care of any changed
1271 or deleted source text.
1272 \o Run \l lupdate to incorporate any new text added to the
1273 application. \l lupdate synchronizes the user-visible text from the
1274 application with the translations; it does not destroy any data.
1275 \o Steps 2 and 3 are repeated as often as necessary.
1276 \o When a release of the application is needed \l lrelease is run to
1277 read the \c .ts files and produce the \c .qm files used by the
1278 application at runtime.
1281 For \l lupdate to work successfully, it must know which translation
1282 files to produce. The files are simply listed in the application's \c
1283 .pro Qt project file, for example:
1285 \snippet examples/linguist/arrowpad/arrowpad.pro 1
1287 If your sources contain genuine non-Latin1 strings, \l lupdate needs
1288 to be told about it in the \c .pro file by using, for example,
1295 See the \l lupdate and \l lrelease sections.
1297 \section2 Loading Translations
1299 \snippet examples/linguist/hellotr/main.cpp 1
1300 \snippet examples/linguist/hellotr/main.cpp 3
1302 This is how a simple \c main() function of a Qt application begins.
1304 \snippet examples/linguist/hellotr/main.cpp 1
1305 \snippet examples/linguist/hellotr/main.cpp 4
1307 For a translation-aware application a translator object is created, a
1308 translation is loaded and the translator object installed into the
1311 \snippet examples/linguist/arrowpad/main.cpp 0
1312 \snippet examples/linguist/arrowpad/main.cpp 1
1314 For non-Latin1 strings in the sources you will also need for example:
1317 QTextCodec::setCodecForTr(QTextCodec::codecForName("utf8"));
1320 In production applications a more flexible approach, for example,
1321 loading translations according to locale, might be more appropriate. If
1322 the \c .ts files are all named according to a convention such as
1323 \e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the
1324 code above will load the current locale's translation at runtime.
1326 If there is no translation file for the current locale the application
1327 will fall back to using the original source text.
1329 Note that if you need to programmatically add translations at
1330 runtime, you can reimplement QTranslator::translate().
1332 \section2 Making the Application Translate User-Visible Strings
1334 User-visible strings are marked as translation targets by wrapping them
1335 in a \c tr() call, for example:
1337 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6
1341 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7
1343 All QObject subclasses that use the \c Q_OBJECT macro implement
1344 the \c tr() function.
1346 Although the \c tr() call is normally made directly since it is
1347 usually called as a member function of a QObject subclass, in
1348 other cases an explicit class name can be supplied, for example:
1350 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8
1354 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9
1356 \section2 Distinguishing Identical Strings That Require Different Translations
1358 The \l lupdate program automatically provides a \e context for every
1359 source text. This context is the class name of the class that contains
1360 the \c tr() call. This is sufficient in the vast majority of cases.
1361 Sometimes however, the translator will need further information to
1362 uniquely identify a source text; for example, a dialog that contained
1363 two separate frames, each of which contained an "Enabled" option would
1364 need each identified because in some languages the translation would
1365 differ between the two. This is easily achieved using the
1366 two argument form of the \c tr() call, e.g.
1368 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10
1372 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11
1374 Ctrl key accelerators are also translatable:
1376 \snippet examples/linguist/trollprint/mainwindow.cpp 2
1378 It is strongly recommended that the two argument form of \c tr() is used
1379 for Ctrl key accelerators. The second argument is the only clue the
1380 translator has as to the function performed by the accelerator.
1382 \section2 Helping the Translator with Navigation Information
1384 In large complex applications it may be difficult for the translator to
1385 see where a particular source text comes from. This problem can be
1386 solved by adding a comment using the keyword \e TRANSLATOR which
1387 describes the navigation steps to reach the text in question; e.g.
1389 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12
1391 These comments are particularly useful for widget classes.
1393 \section2 Handling Plural Forms
1395 Qt includes a \c tr() overload that will make it very easy to
1396 write "plural-aware" internationalized applications. This overload
1397 has the following signature:
1399 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17
1401 Depending on the value of \c n, the \c tr() function will return a different
1402 translation, with the correct grammatical number for the target language.
1403 Also, any occurrence of \c %n is replaced with \c{n}'s value. For example:
1405 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18
1407 If a French translation is loaded, this will expand to "0 item
1408 remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items
1409 remplac\unicode{233}s", etc., depending on \c{n}'s value.
1410 And if no translation is loaded, the orignal string is used, with \c %n
1411 replaced with count's value (e.g., "6 item(s) replaced").
1413 To handle plural forms in the native language, you need to load a
1414 translation file for this language, too. \l lupdate has the
1415 \c -pluralonly command line option, which allows the creation of
1416 \c .ts files containing only entries with plural forms.
1418 See the \l{http://qt.nokia.com/doc/qq/}{Qt Quarterly} Article
1419 \l{http://qt.nokia.com/doc/qq/qq19-plurals.html}{Plural Forms in Translations}
1420 for further details on this issue.
1422 \section2 Coping With C++ Namespaces
1424 C++ namespaces and the \c {using namespace} statement can confuse
1425 \l lupdate. It will interpret \c MyClass::tr() as meaning just
1426 that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is
1427 defined in the \c MyNamespace namespace. Runtime translation of
1428 these strings will fail because of that.
1430 You can work around this limitation by putting a \e TRANSLATOR
1431 comment at the beginning of the source files that use \c
1434 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13
1436 After the comment, all references to \c MyClass::tr() will be
1437 understood as meaning \c MyNamespace::MyClass::tr().
1439 \section2 Translating Text That is Outside of a QObject Subclass
1441 \section3 Using QCoreApplication::translate()
1443 If the quoted text is not in a member function of a QObject subclass,
1444 use either the tr() function of an appropriate class, or the
1445 QCoreApplication::translate() function directly:
1447 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14
1449 \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP()
1451 If you need to have translatable text completely outside a function,
1452 there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP().
1453 These macros merely mark the text for extraction by \l{lupdate}.
1454 The macros expand to just the text (without the context).
1456 Example of QT_TR_NOOP():
1457 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15
1459 Example of QT_TRANSLATE_NOOP():
1460 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16
1464 Three tutorials are presented:
1467 \o \l{linguist/hellotr}{Hello tr()} demonstrates the creation of
1468 a \l QTranslator object. It also shows the simplest use of
1469 the \c tr() function to mark user-visible source text for
1472 \o \l{linguist/arrowpad}{Arrow Pad} explains how to make the application load the
1473 translation file applicable to the current locale. It also shows the
1474 use of the two-argument form of \c tr() which provides additional
1475 information to the translator.
1477 \o \l{linguist/trollprint}{Troll Print} explains how
1478 identical source texts can be distinguished even when they occur in
1479 the same context. This tutorial also discusses how the translation
1480 tools help minimize the translator's work when an application is
1484 These tutorials cover all that you need to know to prepare your Qt
1485 applications for translation.
1487 At the beginning of a project add the translation source files to be
1488 used to the project file and add calls to \l lupdate and \l lrelease to
1491 During the project all the programmer must do is wrap any user-visible
1492 text in \c tr() calls. They should also use the two argument form for
1493 Ctrl key accelerators, or when asked by the translator for the cases
1494 where the same text translates into two different forms in the same
1495 context. The programmer should also include \c TRANSLATION comments to
1496 help the translator navigate the application.
1500 \page linguist-ts-file-format.html
1501 \title Qt Linguist Manual: TS File Format
1503 \contentspage {Qt Linguist Manual}{Contents}
1504 \previouspage Qt Linguist Manual: Programmers
1506 The \c .ts file format used by \QL is described by the
1507 \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below,
1508 which we include for your convenience. Be aware that the format
1509 may change in future Qt releases.
1511 \quotefile tools/linguist/shared/ts.dtd