summaryrefslogtreecommitdiffstats
path: root/doc/src/internationalization/linguist-manual.qdoc
blob: a67d65ad1bcdef702e1c01a6544cbdf081ff415b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page linguist-manual.html
    \title Qt Linguist Manual
    \ingroup qttools

    \startpage {index.html}{Qt Reference Documentation}
    \nextpage Qt Linguist Manual: Release Manager

    \keyword Qt Linguist

    Qt provides excellent support for translating applications into local
    languages. This Guide explains how to use Qt's translation tools for
    each of the roles involved in translating an application. The Guide
    begins with a brief overview of the issues that must be considered,
    followed by chapters devoted to each role and the supporting tools
    provided.

    The \l{linguist-manager.html}{Release Manager} chapter is aimed
    at the person with overall responsibility for the release of the
    application. They will typically coordinate the work of the
    software engineers and the translator. The chapter describes the
    use of two tools. The \l{lupdate} tool is used to synchronize
    source code and translations. The \l{lrelease} tool is used to
    create runtime translation files for use by the released
    application.

    The \l{linguist-translators.html}{Translators} chapter is for
    translators. It describes the use of the \QL tool.
    No computer knowledge beyond the ability to start a program and
    use a text editor or word processor is required.

    The \l{linguist-programmers.html}{Programmers} chapter is for Qt
    programmers. It explains how to create Qt applications that are
    able to use translated text. It also provides guidance on how to
    help the translator identify the context in which phrases appear.
    This chapter's three short tutorials cover everything the
    programmer needs to do.

    \section1 Overview of the Translation Process

    Most of the text that must be translated in an application program
    consists of either single words or short phrases. These typically
    appear as window titles, menu items, pop-up help text (balloon help),
    and labels to buttons, check boxes and radio buttons.

    The phrases are entered into the source code by the programmer in
    their native language using a simple but special syntax to identify
    that the phrases require translation. The Qt tools provide context
    information for each of the phrases to help the translator, and the
    programmer is able to add additional context information to phrases
    when necessary. The release manager generates a set of translation
    files that are produced from the source files and passes these to the
    translator. The translator opens the translation files using \QL, 
    enters their translations and saves the results back into
    the translation files, which they pass back to the release manager.
    The release manager then generates fast compact versions of these
    translation files ready for use by the application. The tools are
    designed to be used in repeated cycles as applications change and
    evolve, preserving existing translations and making it easy to
    identify which new translations are required. \QL also
    provides a phrase book facility to help ensure consistent
    translations across multiple applications and projects.

    Translators and programmers must address a number of issues because
    of the subtleties and complexities of human language:

    \list

    \o A single phrase may need to be translated into several
    different forms depending on context, e.g. \e open in English
    might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen,
    "open internet connection", in German.

    \o Keyboard accelerators may need to be changed but without
    introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt"
    in Norwegian which doesn't contain a "Q". We cannot use a letter
    that is already in use - unless we change several accelerators.

    \o Phrases that contain variables, for example, "The 25 files
    selected will take 63 seconds to process", where the two numbers
    are inserted programmatically at runtime may need to be reworded
    because in a different language the word order and therefore the
    placement of the variables may have to change.

    \endlist

    The Qt translation tools provide clear and simple solutions to these
    issues.

    Chapters:

    \list
    \o \l{Qt Linguist Manual: Release Manager}{Release Manager}
    \o \l{Qt Linguist Manual: Translators}{Translators}
    \o \l{Qt Linguist Manual: Programmers}{Programmers}
    \o \l{Qt Linguist Manual: TS File Format}{TS File Format}
    \endlist

    \QL and \c lupdate are able to import and export XML Localization
    Interchange File Format (XLIFF) files, making it possible to take
    advantage of tools and translation services that work with this
    format. See the \l{Qt Linguist Manual: Translators} {Translators}
    section for more information on working with these files.

    \table

    \row \o{1,2} \inlineimage wVista-Cert-border-small.png
    \o \e{Qt Linguist 4.3 is Certified for Windows Vista}
    
    \row \o Windows Vista and the Windows Vista Start button are
    trademarks or registered trademarks of Microsoft Corporation in
    the United States and/or other countries.

    \endtable
*/

/*!
    \page linguist-manager.html
    \title Qt Linguist Manual: Release Manager

    \contentspage {Qt Linguist Manual}{Contents}
    \previouspage Qt Linguist Manual
    \nextpage Qt Linguist Manual: Translators

    \keyword lupdate
    \keyword lrelease

    Two tools are provided for the release manager, \l lupdate and \l
    lrelease. These tools can process \l qmake project files, or operate
    directly on the file system.

    \section1 Qt Project Files

    The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease}
    {lrelease} is by specifing a \c .pro Qt project file. There must
    be an entry in the \c TRANSLATIONS section of the project file for
    each language that is additional to the native language. A typical
    entry looks like this:

    \snippet examples/linguist/arrowpad/arrowpad.pro 1

    Using a locale within the translation file name is useful for
    determining which language to load at runtime. This is explained
    in the \l{linguist-programmers.html} {Programmers} chapter.

    An example of a complete \c .pro file with four translation source
    files:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0
    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1

    QTextCodec::setCodecForTr() makes it possible to choose a 8-bit
    encoding for literal strings that appear within \c tr() calls.
    This is useful for applications whose source language is, for
    example, Chinese or Japanese. If no encoding is set, \c tr() uses
    Latin1.

    If you do use the QTextCodec::codecForTr() mechanism in your
    application, \QL needs you to set the \c CODECFORTR
    entry in the \c .pro file as well. For example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1

    Also, if your compiler uses a different encoding for its runtime
    system as for its source code and you want to use  non-ASCII
    characters in string literals, you will need to set the \c
    CODECFORSRC. For example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2

    Microsoft Visual Studio 2005 .NET appears to be the only compiler
    for which this is necessary. However, if you want to write
    portable code, we recommend that you avoid non-ASCII characters
    in your source files. You can still specify non-ASCII characters
    portably using escape sequences, for example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3

    \target lupdate manual
    \section1 lupdate

    Usage: \c {lupdate myproject.pro}

    \l lupdate is a command line tool that finds the translatable
    strings in the specified source, header and \e {Qt Designer}
    interface files, and produces or updates \c .ts translation
    files. The files to process and the files to update can be set at
    the command line, or provided in a \c .pro file specified as an
    command line argument. The produced translation files are given to
    the translator who uses \QL to read the files and insert the
    translations.

    Companies that have their own translators in-house may find it
    useful to run \l lupdate regularly, perhaps monthly, as the
    application develops. This will lead to a fairly low volume of
    translation work spread evenly over the life of the project and
    will allow the translators to support a number of projects
    simultaneously.

    Companies that hire in translators as required may prefer to run
    \l lupdate only a few times in the application's life cycle, the
    first time might be just before the first test phase. This will
    provide the translator with a substantial single block of work and
    any bugs that the translator detects may easily be included with
    those found during the initial test phase. The second and any
    subsequent \l lupdate runs would probably take place during the
    final beta phase.

    The TS file format is a simple human-readable XML format that
    can be used with version control systems if required. \c lupdate
    can also process Localization Interchange File Format (XLIFF)
    format files; files in this format typically have file names that
    end with the \c .xlf suffix.

    Pass the \c -help option to \c lupdate to obtain the list of
    supported options:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4

    \QL is also able to import and export XLIFF files. See the
    \l{Qt Linguist Manual: Translators}{Translators} section for more
    information.

    \section1 lrelease

    Usage: \c {lrelease myproject.pro}

    \l lrelease is a command line tool that produces QM files out
    of TS files. The QM file format is a compact binary format
    that is used by the localized application. It provides extremely
    fast lookups for translations. The TS files \l lrelease
    processes can be specified at the command line, or given
    indirectly by a Qt \c .pro project file.

    This tool is run whenever a release of the application is to be
    made, from initial test version through to final release
    version. If the QM files are not created, e.g. because an
    alpha release is required before any translation has been
    undertaken, the application will run perfectly well using the text
    the programmers placed in the source files. Once the QM files
    are available the application will detect them and use them
    automatically.

    Note that lrelease will only incorporate translations that are
    marked as "finished". Otherwise the original text will be used
    instead.

    Pass the \c -help option to \c lrelease to obtain the list of
    supported options:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5

    \section1 Missing Translations

    Both \l lupdate and \l lrelease may be used with TS
    translation source files which are incomplete. Missing
    translations will be replaced with the native language phrases at
    runtime.  
*/

/*!
    \page linguist-translators.html
    \title Qt Linguist Manual: Translators

    \contentspage {Qt Linguist Manual}{Contents}
    \previouspage Qt Linguist Manual: Release Manager
    \nextpage Qt Linguist Manual: Programmers

    Contents

    \tableofcontents

    \section1 The One Minute Guide to Using Qt Linguist

    \QL is a tool for adding translations to Qt applications. Run \QL
    from the taskbar menu, or by double clicking the desktop icon, or
    by entering the command \c {linguist} at the command line. Once
    \QL has started, choose \menu{File|Open} from the \l{menubar}
    {menu bar} and select a translation source (TS file) to
    load. If you do not have a TS file, see the \l {Qt Linguist
    Manual: Release Manager} {release manager manual} to learn how to
    generate one.

    The \QL main window is divided into several, dockable subwindows
    arranged around a central \l{The Translation Area} {translation
    area}. The \l{Context Window} {context list} is normally shown
    on the left, and the \l{Sources and Forms Window} {source code},
    \l{Strings Window} {string list}, and either the \l{Phrases and 
    Guesses Window} {prhrases and guesses}, or the \l{Warnings Window} 
    {warnings} are shown above and below the \l{The Translation Area}
    {translations area}.

    With a translation file loaded, select a context from the
    \l{Context Window} {context list} on the left. Selecting a context
    loads the translatable strings found in that context into the
    \l{Strings Window} {string list}. Selecting one of the strings
    copies that string as the \key{Source text} in the \l{The
    Translation Area} {translation area}. Click in the text entry
    widget below the copied string and type your translation for that
    string. To accept the translation, either press the green
    \key{tick mark} button on the toolbar, or click the icon to the
    left of the selected source string in the string list. Repeat this
    process until all strings in the string list are marked with
    \inlineimage linguist-check-on.png 
    or
    \inlineimage linguist-check-warning.png 
    . Then select the next context and continue.

    Translation options are shown in the \l{Phrases and Guesses
    Window} {phrases and guesses window}. If the phrases and guesses
    window is not visible, click the \key{Phrases and guesses} tab at
    the bottom of the main window. The phrases and guesses window
    shows possible translations for the current string. These
    translation "guesses" have been read from phrase books
    (\menu{Phrases|Open Phrase Book...}).  The current string's
    current translation is also shown here. To select a guess, double
    click it in the prases and guesses window or use the keyboard
    shortcut shown to the right of the guess.

    \QL can automatically check whether your translation strings pass
    a list of \l{Validation Tests} {validation tests}. Validation test
    failures are shown in the \l{Warnings Window} {warnings window}.
    If the warnings window is not visible, click the \key{Warnings}
    tab at the bottom of the main window.

    Finally, if the source code for the contexts is accessible, the
    \l{Sources and Forms Window} {source code window} shows the
    context where the current string is used. If the source code
    window is not visible, click the \key{Sources and Forms} tab at
    the bottom of the main window.

    At the end of the session choose \menu{File|Save} from the menu
    bar and then \menu{File|Exit} to quit.

    \section1 The Qt Linguist Window

    \image linguist-linguist.png "Linguist UI Snapshot"

    This \QL main window is divided into dockable subwindows arranged
    around a central \l{The Translation Area} {translation area}. The
    subwindows are: \l{Context Window} {Context}, \l{Sources and Forms
    Window} {Sources and Forms}, \l{Strings Window} {Strings},
    \l{Phrases and Guesses Window} {Phrases and guesses}, and
    \l{Warnings Window} {Warnings} (hidden in the UI snapsot). The
    translation area is always visible, but the dockable subwindows
    can be activated or deactivated in the \menu{View|Views} menu, and
    dragged around by their title bars and dropped in the translation
    area or even outside the main window.

    \section2 Context Window

    The context window normally appears on the left side of the main
    window. It lists the contexts in which strings to be translated
    appear. The column labeled \e{Context} lists the context names in
    alphabetical order. Each context is the name of a subclass of
    QObject. There can also be a context for QObject itself, which
    contains strings passed to the static function QObject::tr().
    There can also be an \e{<unnamed context>}, which contains strings
    that aren't in a subclass of QObject.

    To the left of the \e{Context} column is a column labeled
    \inlineimage linguist-check-obsolete.png  
    . This column uses the following list of icons to summarize the
    current translation state for each context:

    \list

    \o \inlineimage linguist-check-on.png 
    All strings in the context have been translated, and all the
    translations passed the \l{Validation Tests} {validation tests}.

    \o \inlineimage linguist-check-warning.png 
    All strings in the context have been translated or marked as
    translated, but at least one translation failed the \l{Validation
    Tests} {validation tests}.

    \o \inlineimage linguist-check-off.png
    At least one string in the context has not been translated or is
    not marked as translated.

    \o \inlineimage linguist-check-obsolete.png
    None of the translated strings still appears in the context. This
    usually means the context itself no longer exists in the
    application.

    \endlist

    To the right of the \e{Context} column is the \e{Items} column.
    Each entry in the \e{Items} column is a pair of numbers separated
    by a slash ("/"). The number to the right of the slash is the
    number of translatable strings in the context. The number to the
    left of the slash is the number of those strings that currently
    have translations. i.e., if the numbers are equal, all the
    translatable strings in the context have translations.

    In the UI snapshot above, the \bold{MessageEditor} context is
    selected.  Its \e{Items} entry shows \bold{18/18}, which means it
    has 18 translatable strings and all 18 strings currently have
    translations. However, the context has been marked with the
    \inlineimage linguist-check-warning.png 
    icon, which means that at least one of the current translations 
    failed a \l{Validation Tests} {validation test}. In the 
    \l{Strings Window} {strings window} to the right, we see that one 
    of the strings is indeed marked with the 
    \inlineimage linguist-check-warning.png 
    icon.

    The context window is a dockable window. It can be dragged to
    another position in the main window, or dragged out of the main
    window to be a separate window. If you move the context window,
    \QL remembers the new position and puts the context window there
    whenever you start the program. If the context window has been 
    closed, it can be restored by pressing \key{F6}.

    \section2 Strings Window

    The strings window normally appears on the right in the main
    window, above the \l{The Translation Area} {translation area}. Its
    \e{Source text} column lists all the translatable strings found in
    the current context. Selecting a string makes that string the
    current string in the \l{The Translation Area} {translation area}.

    To the left of the \e{Source text} column is a column labeled
    \inlineimage linguist-check-obsolete.png
    . This column is similar to the one in the \l{Context Window}
    {context window}, but here you can click on the icon to change the
    translation acceptance state for each string in the list. A tick
    mark, green or yellow, means the string has been translated and
    the user has accepted the translation. A question mark means
    either that the user has not accepted the string's translation or
    that the string doesn't have a translation. The table below
    explains the acceptance states and their icons:

    \target String Translation States

    \table
    \header
    \o State
    \o Icon
    \o Description

    \row
    \o Accepted/Correct
    \o \inlineimage linguist-check-on.png
    \o The source string has a translation (possibly empty); the user
    has accepted the translation, and the translation passes all the
    \l{Validation Tests} {validation tests}. If the translation is
    empty, the user has chosen to leave it empty. Click the icon to 
    revoke acceptance of the translation and decrement the number of 
    accepted translations in the \e{Items} column of the \l{Context
    Window} {context list} by 1. The state is reset to 
    \inlineimage linguist-check-off.png 
    if the string has a translation, or to
    \inlineimage linguist-check-empty.png
    if the string's translation is empty. If \c{lupdate} changes the 
    contents of a string, its acceptance state is automatically reset 
    to \inlineimage linguist-check-off.png 
    .

    \row
    \o Accepted/Warnings
    \o \inlineimage linguist-check-warning.png
    \o The user has accepted the translation, but the translation does
    not pass all the \l{Validation Tests} {validation tests}. The
    validation test failures are shown in the \l{Warnings Window}
    {warnings window}. Click the icon to revoke acceptance of the 
    translation. The state is reset to \inlineimage linguist-danger.png 
    , and the number of accepted translations in the \e{Items} column 
    of the \l{Context Window} {context list} is decremented by 1. 
    
    \row
    \o Not Accepted
    \o \inlineimage linguist-check-off.png
    \o The string has a non-empty translation that passes all the 
    \l{Validation Tests} {validation tests}, but the user has not yet 
    accepted the translation. Click the icon or press \key{Ctrl+Enter}
    to accept the translation. The state is reset to  
    \inlineimage linguist-check-on.png
    , and the number of accepted translations in the \e{Items} column 
    of the \l{Context Window} {context list} is incremented by 1.  

    \row
    \o No Translation
    \o \inlineimage linguist-check-empty.png
    \o The string does not have a translation. Click the icon to 
    accpet the empty translation anyway. The state is reset to  
    \inlineimage linguist-check-on.png
    , and the number of accepted translations in the \e{Items} column 
    of the \l{Context Window} {context list} is incremented by 1.

    \row
    \o Validation Failures
    \o \inlineimage linguist-danger.png
    \o The string has a translation, but the translation does not 
    pass all the \l{Validation Tests} {validation tests}. Validation 
    test failures are shown in the \l{Warnings Window} {warnings} 
    window. Click on the icon or press \key{Ctrl+Return} to accept 
    the translation even with validation failures. The state is 
    reset to  \inlineimage linguist-check-warning.png
    . We recommended editing the translation to fix the causes of 
    the validation failures. The state will reset automatically to
    \inlineimage linguist-check-off.png
    , when all the failures have been fixed. 

    \row
    \o Obsolete
    \o \inlineimage linguist-check-obsolete.png
    \o The string is obsolete. It is no longer used in the context.
    See the \l{Qt Linguist Manual: Release Manager} {Release Manager}
    for instructions on how to remove obsolete messages from the file.

    \endtable

    The string list is a dockable subwindow. If it has been closed,
    restored it by pressing \key{F7}.

    \section2 The Translation Area

    The translation area is in the middle of the main window, to the
    right of the \l{Context Window} {context list}. It doesn't have a
    title bar, so you can't drag it around. Instead, you drag and drop
    the other subwindows to arrange them around the translation area.
    The string currently selected in the \l{Strings Window} {string
    list} appears at the top of the translation area, under the label
    \menu{Source text}. Note that all blanks in the source text have
    been replaced by "." so the translator can see the spacing
    required within the text.

    If the developer provides a \l{QObject::tr()} {disambiguating
    comment}, it will appear below the source text area, under the
    label \menu{Developer comments}. 

    Below the source text and optional developer comments are two text
    entry widgets for the translator, one for entering the translation
    of the current string, and one for the translator to enter an
    optional comment to be read by other translators. 

    When \l{Translating Multiple Languages Simultaneously} {multiple
    languages} are being translated, this sequence of fields is
    repeated for each language. See aso \l {Changing the Target
    Locale}.

    \section2 Phrases and Guesses Window

    If the current string in the \l{Strings Window} {string list}
    appears in one or more of the \l{Phrase Books} {phrase books}
    that have been loaded, the current string and its phrase book
    translation(s) will be listed in this window. If the current
    string is the same as, or similar to, another string that has
    already been translated, that other string and its translation
    will also be listed in this window. 

    To use a translation from the Phrases and Guesses Window, you can
    double click the translation, and it will be copied into the
    translation area, or you can use the translation's \e{Guess}
    hotkey on the right. You can also press \key{F10} to move the
    focus to the Phrases and Guesses Window, then use the up and down
    arrow keys to find the desired translation, and and then press
    \key{Enter} to copy it to the translation area.  If you decide
    that you don't want to copy a phrase after all, press \key{Esc} to
    return the focus to the translation area.

    The Phrases and Guesses Window is a dockable window. If it has
    been closed, it can be made visible by pressing the \e{Phrases and
    guesses} tab at the bottom of the window, or by pressing
    \key{F10}.

    \section2 Sources and Forms Window

    If the source files containing the translatable strings are
    available to \QL, this window shows the source context of the
    current string in the \l{Strings Window} {string list}. The source
    code line containing the current string should be shown and
    highlighted. If the file containing the source string is not
    found, the expected absolute file path is shown.

    If the source context shows the wrong source line, it probably
    means the translation file is out of sync with the source files.
    To re-sync the translation file with the source files, see the
    \l{lupdate manual} {lupdate manual}.

    The Sources and Forms window is a dockable window. If it has been
    closed, it can be made visible again by pressing the \e{Sources
    and Forms} tab at the bottom of the window, or by pressing
    \key{F9}.

    \section2 Warnings Window

    If the translation you enter for the current string fails any of
    the active \l{Validation Tests} {validation tests}, the failures
    are listed in the warnings window. The first of these failure
    messages is also shown in the status bar at the bottom of the main
    window. Note that only \e{active} validation tests are
    reported. To see which validation tests are currently active, or
    to activate or deactivate tests, use the \menu{Validation} menu
    from the \l{menubar}{menu bar}.

    The Warnings window is a dockable window. If it has been closed,
    it can be made visible by pressing the \e{Warnings} tab at the
    bottom of the window, or by pressing \key{F8}.

    \target multiple languages
    \section2 Translating Multiple Languages Simultaneously

    Qt Linguist can now load and edit multiple translation files
    simultaneously. One use for this is the case where you know two
    languages better than you know English (Polish and Japanese, say),
    and you are given an application's Polish translation file and
    asked to update the application's Japanese translation file. You
    are more comfortable translating Polish to Japanese than you are
    translating English to Japanese. 

    Below is the UI snapshot shown earlier, but this time with both
    \e{Polish} and \e{Japanese} translation files loaded.

    \image linguist-linguist_2.png 

    The first thing to notice is that the \l{The Translation Area}
    {translation area} has text editing areas for both Polish and
    Japanese, and these are color-coded for easier separation.
    Second, the \l{Context Window} and the \l{Strings Window} both
    have two clomuns labeled \inlineimage linguist-check-obsolete.png
    instead of one, and although it may be hard to tell, these columns
    are also color-coded with the same colors. The left-most column in
    either case applies to the top-most language area (Polish above)
    in the \l{The Translation Area} {translation area}, and the
    right-most column applies to the bottom language area.

    The \e{Items} column in the \l{Context Window} combines the values
    for both languages. The best way to see this is to look at the
    value for the \bold{MessageEditor} context, which is the one
    selected in the snapshot shown above. Recall that in the first UI
    snapshot (Polish only), the numbers for this context were
    \e{18/18}, meaning 18 translatable strings had been found in the
    context, and all 18 strings had accepted translations.  In the UI 
    snapshot above, the numbers for the \bold{MessageEditor} context
    are now \e{1/18}, meaning that both languages have 18 translatable
    strings for that context, but for Japanese, only 1 of the 18
    strings has an accepted translation. The 
    \inlineimage linguist-check-off.png 
    icon in the Japanese column means that at least one string in the
    context doesn't have an accepted Japanese translation yet. In fact, 
    17 of the 18 strings don't have accepted Japanese translations yet. 
    We will see \e{18/18} in the \e{Items} column when all 18 strings 
    have accepted translations for all the loaded translation files, 
    e.g., both Polish and Japanese in the snapshot. 

    \section1 Common Tasks

    \section2 Leaving a Translation for Later

    If you wish to leave a translation press \key{Ctrl+L} (Next
    Unfinished) to move to the next unfinished translation. To move to
    the next translation (whether finished or unfinished) press
    \key{Shift+Ctrl+L}. You can also navigate using the Translation
    menu. If you want to go to a different context entirely, click the
    context you want to work on in the Context list, then click the
    source text in the \l{Strings Window} {string list}.

    \section2 Phrases That Require Multiple Translations Depending on Context

    The same phrase may occur in two or more contexts without conflict. Once
    a phrase has been translated in one context, \QL notes
    that the translation has been made and when the translator reaches a
    later occurrence of the same phrase \QL will provide
    the previous translation as a possible translation candidate in the
    \l{Phrases and Guesses Window}.

    If a phrase occurs more than once in a particular context it will
    only be shown once in \QL's \l{Context Window} {context list} and
    the translation will be applied to every occurrence within the
    context.  If the same phrase needs to be translated differently
    within the same context the programmer must provide a
    distinguishing comment for each of the phrases concerned. If such
    comments are used the duplicate phrases will appear in the
    \l{Context Window} {context list}. The programmers comments will
    appear in the \l{The Translation Area} {translation area} on a
    light blue background.

    \section2 Changing Keyboard Accelerators

    A keyboard accelerator is a key combination that, when pressed,
    causes an application to perform an action. There are two kinds of
    keyboard accelerators: Alt key and Ctrl key accelerators.

    \section3 Alt Key Accellerators

    Alt key accelerators are used in menu selection and on buttons.
    The underlined character in a menu item or button label signifies
    that pressing the Alt key with the underlined character will
    perform the same action as clicking the menu item or pressing the
    button.  For example, most applications have a \e{File} menu with
    the "F" in the word "File" underlined. In these applications the
    \e{File} menu can be invoked either by clicking the word "File" on
    the menu bar or by pressing \e{Alt+F}. To identify an accelerator
    key in the translation text ("File") precede it with an ampersand,
    e.g. \e{\&File}. If a string to be translated has an ampersand in
    it, then the translation for that string should also have an
    ampersand in it, preferably in front of the same character. 

    The meaning of an Alt key accelerator can be determined from the
    phrase in which the ampersand is embedded. The translator can
    change the character part of the Alt key accelerator, if the
    translated phrase does not contain the same character or if that
    character has already been used in the translation of some other
    Alt key accelerator. Conflicts with other Alt key accelerators
    must be avoided within a context.  Note that some Alt key
    accelerators, usually those on the menu bar, may apply in other
    contexts.

    \section3 Ctrl Key Accelerators

    Ctrl key accelerators can exist independently of any visual
    control. They are often used to invoke actions in menus that would
    otherwise require multiple keystrokes or mouse clicks. They may
    also be used to perform actions that do not appear in any menu or
    on any button. For example, most applications that have a \e{File}
    menu have a \e{New} submenu item in the \e{File} menu. The \e{New}
    item might appear as "\underline{N}ew Ctrl+N" in the \e{File}
    menu, meaning the \e{New} menu can be invoked by simply pressing
    \key{Ctrl+N}, instead of either clicking \e{File} with the mouse
    and then clicking \e{New} with the mouse, or by entering \e{Alt+F}
    and \e{N}.

    Each Ctrl key accelerator is shown in the \l{Strings Window}
    {string list} as a separte string, e.g. \key{Ctrl+Enter}. Since
    the string doesn't have a context to give it meaning, e.g. like
    the context of the phrase in which an Alt key accelerator appears,
    the translator must rely on the UI developer to include a
    \l{QObject::tr()} {disambiguation comment} to explain the action
    the Ctrl key accelerator is meant to perform. This disambiguating
    comment (if provided by the developer) will appear under
    \e{Developer comments} in the \l{The Translation Area}
    {translation area} under the \e{Source text} area.

    Ideally Ctrl key accelerators are translated simply by copying
    them directly using \e {Copy from source text} in the
    \menu{Translation} menu. However, in some cases the character will
    not make sense in the target language, and it must be
    changed. Whichever character (alpha or digit) is chosen, the
    translation must be in the form "Ctrl+" followed by the upper case
    character.  \e{Qt} will automatically display the correct name at
    runtime. As with Alt key accelerators, if the translator changes
    the character, the new character must not conflict with any other
    Ctrl key accelerator.

    \warning Do not translate the "Alt", "Ctrl" or "Shift" parts of
    the accelerators. \e{Qt} relies on these strings being there. For
    supported languages, \e {Qt} automatically translates these
    strings.

    \section2 Handling Numbered Arguments

    Some phrases contain numbered arguments. A numbered argument is a
    placeholder that will be replaced with text at runtime. A numbered
    argument appears in a source string as a percent sign followed by
    a digit. Consider an example: \c{After processing file %1, file %2
    is next in line}. In this string to be translated, \c{%1} and
    \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%2} will
    be replaced with the first and next file names respectively. The
    same numbered arguments must appear in the translation, but not
    necessarily in the same order. A German translation of the string
    might reverse the phrases, e.g. \c{Datei %2 wird bearbeitet, wenn
    Datei %1 fertig ist}. Both numbered arguments appear in the
    translation, but in the reverse order. \c{%i} will always be
    replaced by the same text in the translation stringss, regardless
    of where argument \e{i} appears in the argument sequence in the
    source string.

    \section2 Reusing Translations

    If the translated text is similar to the source text, choose the
    \e {Copy from source text} entry in the \menu Translation menu (press
    \key{Ctrl+B}) which will copy the source text into the 
    \l{The Translation Area} {translation area}.

    \QL automatically lists possible translations from any open
    \l{Phrase Books} {phrase books} in the \l{Phrases and Guesses
    Window}, as well as similar or identical phrases that have already
    been translated.

    \section2 Changing the Target Locale

    \QL displays the target language in the \l{The Translation Area}
    {translation area}, and adapts the number of input fields for
    plural forms accordingly. If not explicitly set, \QL guesses the
    target language and country by evaluating the translation source
    file name: E.g. \c app_de.ts sets the target language to German,
    and \c app_de_ch.ts sets the target language to German and the
    target country to Switzerland (this also helps loading
    translations for the current locale automatically; see
    \l{linguist-programmers.html}{Programmers Manual} for details).
    If your files do not follow this convention, you can also set the
    locale information explicitly using \e {Translation File Settings}
    in the \menu Edit menu.

    \image linguist-translationfilesettings.png

    \section1 Phrase Books

    A \QL phrase book is a set of source phrases, target
    (translated) phrases, and optional definitions. Typically one phrase book
    will be created per language and family of applications. Phrase books 
    are used to provide a common set of translations to help ensure consistency. 
    They can also be used to avoid duplication of effort since the translations 
    for a family of applications can be produced once in the phrase book.
    If the translator reaches an untranslated phrase that is the same as a
    source phrase in a phrase book, \QL will show the
    phrase book entry in the \l {Phrases and Guesses Window}.

    \section2 Creating and Editing Phrase Books

    \image linguist-phrasebookdialog.png

    Before a phrase book can be edited it must be created or, if it already
    exists, opened. Create a new phrase book by selecting
    \menu{Phrase|New Phrase Book} from the menu bar. You must enter a
    filename and may change the location of the file if you wish. A newly
    created phrase book is automatically opened. Open an existing phrase
    book by choosing \menu{Phrase|Open Phrase Book} from the menu bar.

    The phrase book contents can be displayed and changed by selecting
    \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you
    want to work on. This will pop up the Phrase Book Dialog as shown
    in the image above. To add a new phrase click the \gui{New Phrase} 
    button (or press Alt+N) and type in a new source phrase. Press Tab and 
    type in the translation. Optionally press Tab and enter a definition -- 
    this is useful to distinguish different translations of the same source 
    phrase. This process may be repeated as often as necessary. You can delete 
    a phrase by selecting it in the phrases list and clicking
    Remove Phrase. Click the \gui Close button (press Esc) once you've finished 
    adding (and removing) phrases.

    \section2 Shortcuts for Editing Phrase Books

    You can also create a new phrase book entry directly out of the translation you
    are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing
    \key{Ctrl+T} will add the source text and the content of the first translation 
    field to the current phrase book. If multiple phrase books are loaded,
    you have to specify the phrase book to add the entry to in a dialogue.
    If you detect an error in a phrase book entry that is shown in the 
    \l{Phrases and Guesses Window}, you can also edit it in place by right 
    clicking on the entry, and selecting \menu{Edit}. After fixing the error 
    press \key{Return} to leave the editing mode.

    \section2 Batch Translation

    \image linguist-batchtranslation.png

    Use the batch translation feature of \QL to automatically
    translate source texts that are also in a phrase book. Selecting
    \menu{Tools|Batch Translation} will show you the batch translation dialog,
    which let you configure which phrase books to use in what order during the
    batch translation process. Furthermore you can set whether only entries 
    with no present translation should be considered, and whether batch translated
    entries should be set to finished (see also \l {String Translation States}).

    \section1 Validation Tests

    \QL provides four kinds of validation tests for translations.

    \list 1
    \o \e {Accelerator validation} detects translated phrases
    that do not have an ampersand when the source phrase does and vice
    versa.
    \o \e {Punctuation validation} detects differences in the
    terminating punctuation between source and translated phrases when this
    may be significant, e.g. warns if the source phrase ends with an
    ellipsis, exclamation mark or question mark, and the translated phrase
    doesn't and vice versa.
    \o \e {Phrases validation} detects source phrases that are
    also in the phrase book but whose translation differs from that given in
    the phrase book.
    \o \e {Place marker validation} detects whether the same variables
    (like \c %1, \c %2) are used both in the source text and in the translation.
    \endlist

    Validation may be switched on or off from the menu bar's
    Validation item or using the toolbar buttons. Unfinished phrases
    that fail validation are marked with an exclamation mark in the
    source text pane. Finished phrases will get a yellow tick
    instead. If you switch validation off and then switch it on later,
    \QL will recheck all phrases and mark any that fail
    validation. See also \l{String Translation States}.

    \section1 Form Preview

    \image linguist-previewtool.png

    Forms created by \e{Qt Designer} are stored in special UI files.
    \QL can make use of these UI files to show the translations
    done so far on the form itself. This of course requires access to the UI
    files during the translation process. Activate 
    \menu{Tools|Open/Refresh Form Preview} to open the window shown above.
    The list of UI files \QL has detected are displayed in the Forms
    List on the left hand. If the path to the files has changed, you can load
    the files manually via \menu{File|Open Form...}. Double-click on an entry
    in the Forms List to display the Form File. Select \e{<No Translation>} from
    the toolbar to display the untranslated form.

    \section1 Qt Linguist Reference


    \section2 File Types

    \QL makes use of four kinds of files:

    \list
    \o TS \e {translation source files} \BR are human-readable XML
    files containing source phrases and their translations. These files are
    usually created and updated by \l lupdate and are specific to an
    application.
    \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere
    to the international XML Localization Interchange File Format. \QL
    can be used to edit XLIFF files generated by other programs. For standard
    Qt projects, however, only the TS file format is used.
    \o QM \e {Qt message files} \BR are binary files that contain
    translations used by an application at runtime. These files are
    generated by \l lrelease, but can also be generated by \QL.
    \o \c .qph \e {Qt phrase book files} \BR are human-readable XML
    files containing standard phrases and their translations. These files
    are created and updated by \QL and may be used by any
    number of projects and applications.
    \endlist

    \target menubar
    \section2 The Menu Bar

    \image linguist-menubar.png

    \list
    \o \gui {File}
        \list
        \o \gui {Open... Ctrl+O} \BR pops up an open file dialog from which a
        translation source \c .ts or \c .xlf file can be chosen.
        \o \gui {Recently opened files} \BR shows the TS files that
        have been opened recently, click one to open it.
        \o \gui {Save Ctrl+S} \BR saves the current translation source file.
        \o \gui {Save As...} \BR pops up a save as file dialog so that the
        current translation source file may be saved with a different
        name, format and/or put in a different location.
        \o \gui {Release} \BR create a Qt message QM file with the same base
        name as the current translation source file. The release manager's
        command line tool \l lrelease performs the same function on
        \e all of an application's translation source files.
        \o \gui {Release As...} \BR pops up a save as file dialog. The
        filename entered will be a Qt message QM file of the translation
        based on the current translation source file. The release manager's
        command line tool \l lrelease performs the same function on
        \e all of an application's translation source files.
        \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click
        OK the translation source and the translations will be printed.
        \o \gui {Exit Ctrl+Q} \BR closes \QL.
        \endlist

    \o \gui {Edit}
        \list
        \o \gui {Undo Ctrl+Z} \BR undoes the last editing action in the
        translation pane.
        \o \gui {Redo Ctrl+Y} \BR redoes the last editing action in the
        translation pane.
        \o \gui {Cut Ctrl+X} \BR deletes any highlighted text in the
        translation pane and saves a copy to the clipboard.
        \o \gui {Copy Ctrl+C} \BR copies the highlighted text in the
        translation pane to the clipboard.
        \o \gui {Paste Ctrl+V} \BR pastes the clipboard text into the
        translation pane.
    \omit
        \o \gui {Delete} \BR deletes the highlighted text in the
        translation pane.
    \endomit
        \o \gui {Select All Ctrl+A} \BR selects all the text in the
        translation pane ready for copying or deleting.
        \o \gui {Find... Ctrl+F} \BR pops up the
        Find dialog. When the dialog pops up
        enter the text to be found and click the \gui {Find Next} button.
        Source phrases, translations and comments may be searched.
        \o \gui {Find Next F3} \BR finds the next occurrence of the text that
        was last entered in the Find dialog.
        \o \gui {Search and Translate...} \BR pops up the Search and 
        Replace Dialog. Use this dialog to translate the same text in multiple items.
        \o \gui {Translation File Settings...} \BR let you configure the target
        language and the country/region of a translation source file. 
        \endlist

    \o \gui {Translation}
        \list
        \o \gui {Prev Unfinished Ctrl+K} \BR moves to the nearest previous
        unfinished source phrase (unfinished means untranslated or
        translated but failed validation).
        \o \gui {Next Unfinished Ctrl+L} \BR moves to the next unfinished source
        phrase.
        \o \gui {Prev Shift+Ctrl+K} \BR moves to the previous source phrase.
        \o \gui {Next Shift+Ctrl+L} \BR moves to the next source phrase.
        \o \gui {Done \& Next Ctrl+Enter} \BR mark this phrase as 'done'
        (translated) and move to the next unfinished source phrase.
        \o \gui {Copy from source text Ctrl+B} \BR copies the source text into
        the translation.
        \endlist

    \o \gui {Validation} (See \l{Validation Tests})
        \list
        \o \gui {Accelerators} \BR toggles validation on or off for Alt
        accelerators.
        \o \gui {Ending Punctuation} \BR switches validation on or off
        for phrase ending punctuation, e.g. ellipsis, exclamation mark,
        question mark, etc.
        \o \gui {Phrase Matches} \BR sets validation on or off for
        matching against translations that are in the current phrase book.
        \o \gui {Place Marker Matches} \BR sets validation on or off for
        the use of the same place markers in the source and translation.
        \endlist

    \o \gui {Phrases} (See the section \l {Phrase Books} for details.)
        \list

        \o \gui {New Phrase Book... Ctrl+N} \BR pops up a save as file
        dialog.  You must enter a filename to be used for the phrase
        book and save the file. Once saved you should open the phrase
        book to begin using it.

        \o \gui {Open Phrase Book... Ctrl+H} \BR pops up an open file
        dialog.  Find and choose a phrase book to open.

        \o \gui {Close Phrase Book} \BR displays the list of phrase
        books currently opened. Clicking on one of the items will
        close the phrase book. If the phrase book has been modified, a
        dialog box asks whether \QL should save the changes.

        \o \gui {Edit Phrase Book...} \BR displays the list of phrase
        books currently opened. Clicking on one of the items will open
        the \l{Creating and Editing Phrase Books}{Phrase Book Dialog}
        where you can add, edit or delete phrases.

        \o \gui {Print Phrase Book...} \BR displays the list of phrase
        books currently opened. Clicking on one of the items pops up a
        print dialog.  If you click OK the phrase book will be
        printed.

        \o \gui {Add to Phrase Book Ctrl+T} \BR Adds the source text
        and translation currently shown in the \l{The Translation
        Area} {translation area} to a phrase book.  If multiple phrase
        books are loaded, a dialog box let you specify select one.

        \endlist

  \o \gui {Tools}
        \list

        \o \gui {Batch Translation...} \BR Opens a \l{Batch
        Translation}{dialog} which let you automatically insert
        translations for source texts which are in a phrase book.

        \o \gui {Open/Refresh Form Preview F3} \BR Opens the \l{Form
        Preview}.  This window let you instantly see translations for
        forms created with \QD.  \endlist

  \o \gui {View}
        \list

        \o \gui {Revert Sorting} \BR puts the items in the \l{Context
        Window} {context list} and in the \l{Strings Window} {string
        list} into their original order.

        \o \gui {Display Guesses} \BR turns the display of phrases and
        guesses on or off.

        \o \gui {Statistics} \BR toggles the visibility of the
        Statistics dialog.

        \o \gui {Views} \BR toggles the visibility of the \l{Context
        Window}, \l{Strings Window}, \l{Phrases and Guesses Window},
        \l{Warnings Window}, or \l{Sources and Forms Window}.

        \o \gui {Toolbars} \BR toggles the visibility of the different
        toolbars.

        \endlist

  \o \gui {Help}
        \list
        \o \gui {Manual F1} \BR opens this manual.
        \o \gui {About Qt Linguist} \BR Shows information about \QL.
        \o \gui {About Qt} \BR Shows information about \e{Qt}.
        \o \gui {What's This? Shift+F1} \BR Click on one item in the main window 
        to get additional information about it.
        \endlist

    \endlist

    \section2 The Toolbar

    \image linguist-toolbar.png

    \list
    \o \inlineimage linguist-fileopen.png
    \BR
    Pops up the open file dialog to open a new translation source TS file.

    \o \inlineimage linguist-filesave.png
    \BR
    Saves the current translation source TS file.

    \o \inlineimage linguist-fileprint.png
    \BR
    Prints the current translation source TS file.

    \o \inlineimage linguist-phrasebookopen.png
    \BR
    Pops up the file open dialog to open a new phrase book \c .qph file.

    \o \inlineimage linguist-editundo.png
    \BR
    Undoes the last editing action in the translation pane.

    \o \inlineimage linguist-editredo.png
    \BR
    Redoes the last editing action in the translation pane.

    \o \inlineimage linguist-editcut.png
    \BR
    Deletes any highlighted text in the translation pane and save a copy to
    the clipboard.

    \o \inlineimage linguist-editcopy.png
    \BR
    Copies the highlighted text in the translation pane to the clipboard.

    \o \inlineimage linguist-editpaste.png
    \BR
    Pastes the clipboard text into the translation pane.

    \o \inlineimage linguist-editfind.png
    \BR
    Pops up the Find dialog .

    \o \inlineimage linguist-prev.png
    \BR
    Moves to the previous source phrase.

    \o \inlineimage linguist-next.png
    \BR
    Moves to the next source phrase.

    \o \inlineimage linguist-prevunfinished.png
    \BR
    Moves to the previous unfinished source phrase.

    \o \inlineimage linguist-nextunfinished.png
    \BR
    Moves to the next unfinished source phrase.

    \o \inlineimage linguist-doneandnext.png
    \BR
    Marks the phrase as 'done' (translated) and move to the next
    unfinished source phrase.

    \o \inlineimage linguist-validateaccelerators.png
    \BR
    Toggles accelerator validation on and off.

    \o \inlineimage linguist-validatepunctuation.png
    \BR
    Toggles phrase ending punctuation validation on and off.

    \o \inlineimage linguist-validatephrases.png
    \BR
    Toggles phrase book validation on or off.

    \o \inlineimage linguist-validateplacemarkers.png
    \BR
    Toggles place marker validation on or off.

    \endlist

*/

/*!
    \page linguist-programmers.html
    \title Qt Linguist Manual: Programmers

    \contentspage {Qt Linguist Manual}{Contents}
    \previouspage Qt Linguist Manual: Translators
    \nextpage Qt Linguist Manual: TS File Format

    Support for multiple languages is extremely simple in Qt
    applications, and adds little overhead to the programmer's workload.

    Qt minimizes the performance cost of using translations by
    translating the phrases for each window as they are created. In most
    applications the main window is created just once. Dialogs are often
    created once and then shown and hidden as required. Once the initial
    translation has taken place there is no further runtime overhead for
    the translated windows. Only those windows that are created,
    destroyed and subsequently created will have a translation
    performance cost.

    Creating applications that can switch language at runtime is possible
    with Qt, but requires a certain amount of programmer intervention and
    will of course incur some runtime performance cost.

    \section1 Making the Application Translation-Aware

    Programmers should make their application look for and load the
    appropriate translation file and mark user-visible text and Ctrl
    keyboard accelerators as targets for translation.

    Each piece of text that requires translating requires context to help
    the translator identify where in the program the text occurs. In the
    case of multiple identical texts that require different translations,
    the translator also requires some information to disambiguate the
    source texts. Marking text for translation will automatically cause
    the class name to be used as basic context information. In some cases
    the programmer may be required to add additional information to help
    the translator.

    \section2 Creating Translation Files

    Translation files consist of all the user-visible text and Ctrl key
    accelerators in an application and translations of that text.
    Translation files are created as follows:

    \list 1
    \o Run \l lupdate initially to generate the first set of TS
    translation source files with all the user-visible text but no
    translations.
    \o The TS files are given to the translator who adds translations
    using \QL. \QL takes care of any changed
    or deleted source text.
    \o Run \l lupdate to incorporate any new text added to the
    application. \l lupdate synchronizes the user-visible text from the
    application with the translations; it does not destroy any data.
    \o Steps 2 and 3 are repeated as often as necessary.
    \o When a release of the application is needed \l lrelease is run to
    read the TS files and produce the QM files used by the
    application at runtime.
    \endlist

    For \l lupdate to work successfully, it must know which translation
    files to produce. The files are simply listed in the application's \c
    .pro Qt project file, for example:

    \snippet examples/linguist/arrowpad/arrowpad.pro 1

    If your sources contain genuine non-Latin1 strings, \l lupdate needs
    to be told about it in the \c .pro file by using, for example,
    the following line:

    \code
        CODECFORTR = UTF-8
    \endcode
    
    See the \l lupdate and \l lrelease sections.

    \section2 Loading Translations

    \snippet examples/linguist/hellotr/main.cpp 1
    \snippet examples/linguist/hellotr/main.cpp 3

    This is how a simple \c main() function of a Qt application begins.

    \snippet examples/linguist/hellotr/main.cpp 1
    \snippet examples/linguist/hellotr/main.cpp 4

    For a translation-aware application a translator object is created, a
    translation is loaded and the translator object installed into the
    application.

    \snippet examples/linguist/arrowpad/main.cpp 0
    \snippet examples/linguist/arrowpad/main.cpp 1

    For non-Latin1 strings in the sources you will also need for example:

    \code
            QTextCodec::setCodecForTr(QTextCodec::codecForName("utf8"));
    \endcode

    In production applications a more flexible approach, for example,
    loading translations according to locale, might be more appropriate. If
    the TS files are all named according to a convention such as
    \e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the
    code above will load the current locale's translation at runtime.

    If there is no translation file for the current locale the application
    will fall back to using the original source text.

    Note that if you need to programmatically add translations at
    runtime, you can reimplement QTranslator::translate().

    \section2 Making the Application Translate User-Visible Strings

    User-visible strings are marked as translation targets by wrapping them
    in a \c tr() call, for example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6

    would become

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7

    All QObject subclasses that use the \c Q_OBJECT macro implement
    the \c tr() function.

    Although the \c tr() call is normally made directly since it is
    usually called as a member function of a QObject subclass, in
    other cases an explicit class name can be supplied, for example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8

    or

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9

    \section2 Distinguishing Identical Strings That Require Different Translations

    The \l lupdate program automatically provides a \e context for every
    source text. This context is the class name of the class that contains
    the \c tr() call. This is sufficient in the vast majority of cases.
    Sometimes however, the translator will need further information to
    uniquely identify a source text; for example, a dialog that contained
    two separate frames, each of which contained an "Enabled" option would
    need each identified because in some languages the translation would
    differ between the two. This is easily achieved using the
    two argument form of the \c tr() call, e.g.

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10

    and

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11

    Ctrl key accelerators are also translatable:

    \snippet examples/linguist/trollprint/mainwindow.cpp 2

    It is strongly recommended that the two argument form of \c tr() is used
    for Ctrl key accelerators. The second argument is the only clue the
    translator has as to the function performed by the accelerator.

    \section2 Helping the Translator with Navigation Information

    In large complex applications it may be difficult for the translator to
    see where a particular source text comes from. This problem can be
    solved by adding a comment using the keyword \e TRANSLATOR which
    describes the navigation steps to reach the text in question; e.g.

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12

    These comments are particularly useful for widget classes.

    \section2 Handling Plural Forms

    Qt includes a \c tr() overload that will make it very easy to 
    write "plural-aware" internationalized applications. This overload 
    has the following signature:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17

    Depending on the value of \c n, the \c tr() function will return a different 
    translation, with the correct grammatical number for the target language. 
    Also, any occurrence of \c %n is replaced with \c{n}'s value. For example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18

    If a French translation is loaded, this will expand to "0 item 
    remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items 
    remplac\unicode{233}s", etc., depending on \c{n}'s value. 
    And if no translation is loaded, the orignal string is used, with \c %n 
    replaced with count's value (e.g., "6 item(s) replaced").

    To handle plural forms in the native language, you need to load a 
    translation file for this language, too. \l lupdate has the 
    \c -pluralonly command line option, which allows the creation of
    TS files containing only entries with plural forms.

    See the \l{http://qt.nokia.com/doc/qq/}{Qt Quarterly} Article 
    \l{http://qt.nokia.com/doc/qq/qq19-plurals.html}{Plural Forms in Translations}
    for further details on this issue.

    \section2 Coping With C++ Namespaces

    C++ namespaces and the \c {using namespace} statement can confuse
    \l lupdate. It will interpret \c MyClass::tr() as meaning just
    that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is
    defined in the \c MyNamespace namespace. Runtime translation of
    these strings will fail because of that.

    You can work around this limitation by putting a \e TRANSLATOR
    comment at the beginning of the source files that use \c
    MyClass::tr():

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13

    After the comment, all references to \c MyClass::tr() will be
    understood as meaning \c MyNamespace::MyClass::tr().

    \section2 Translating Text That is Outside of a QObject Subclass

    \section3 Using QCoreApplication::translate()

    If the quoted text is not in a member function of a QObject subclass,
    use either the tr() function of an appropriate class, or the
    QCoreApplication::translate() function directly:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14

    \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP()

    If you need to have translatable text completely outside a function,
    there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP().
    These macros merely mark the text for extraction by \l{lupdate}.
    The macros expand to just the text (without the context).

    Example of QT_TR_NOOP():
    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15

    Example of QT_TRANSLATE_NOOP():
    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16

    \section1 Tutorials

    Three tutorials are presented:

    \list 1
    \o \l{linguist/hellotr}{Hello tr()} demonstrates the creation of
        a \l QTranslator object. It also shows the simplest use of
        the \c tr() function to mark user-visible source text for
        translation.

    \o \l{linguist/arrowpad}{Arrow Pad} explains how to make the application load the
       translation file applicable to the current locale. It also shows the
       use of the two-argument form of \c tr() which provides additional
       information to the translator.

    \o \l{linguist/trollprint}{Troll Print} explains how
        identical source texts can be distinguished even when they occur in
        the same context. This tutorial also discusses how the translation
        tools help minimize the translator's work when an application is
        upgraded.
    \endlist

    These tutorials cover all that you need to know to prepare your Qt
    applications for translation.

    At the beginning of a project add the translation source files to be
    used to the project file and add calls to \l lupdate and \l lrelease to
    the makefile.

    During the project all the programmer must do is wrap any user-visible
    text in \c tr() calls. They should also use the two argument form for
    Ctrl key accelerators, or when asked by the translator for the cases
    where the same text translates into two different forms in the same
    context. The programmer should also include \c TRANSLATION comments to
    help the translator navigate the application.
*/

/*!
    \page linguist-ts-file-format.html
    \title Qt Linguist Manual: TS File Format

    \contentspage {Qt Linguist Manual}{Contents}
    \previouspage Qt Linguist Manual: Programmers

    The TS file format used by \QL is described by the
    \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below,
    which we include for your convenience. Be aware that the format
    may change in future Qt releases.

    \quotefile tools/linguist/shared/ts.dtd
    
*/