summaryrefslogtreecommitdiffstats
path: root/tde-i18n-en_GB/docs/tdesdk/kbabel/using.docbook
blob: 9741d7ba9a6e4e89bd3e44bd21f031b85be664c2 (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
<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"
> -->
<!-- Uncomment the previous two lines to validate this document -->
<!-- standalone.  Be sure to recomment them before attempting to -->
<!-- process index.docbook -->

<chapter id="using-kbabel">
<chapterinfo>
<!-- Fill in this section if this document has a different author -->
<authorgroup>
<author>
<personname
><firstname
></firstname
><surname
></surname
></personname>
</author>
</authorgroup>

<othercredit role="translator"
><firstname
>Alex</firstname
><surname
>Walker</surname
><affiliation
><address
><email
>alex@x3ja.co.uk</email
></address
></affiliation
><contrib
>Conversion to British English</contrib
></othercredit
> 
</chapterinfo>


<title
>Using &kbabel;</title>

<sect1 id="using-introduction">
<title
>Introduction</title>

<para
>Usually program messages and documentation are written in English. Using a framework made of a set of tools and libraries, it is possible to have your favourite applications speak your native non-English language. This process of adapting an application to a specific language is known as localisation. The localisation process includes translating the program's interfaces and documentation to the various languages users need and, in some countries or regions, making the inputs and outputs conform to particular conventions. &kbabel; is a tool which will assist you in the internationalisation process to make an application's interface speak many languages.</para>

<para
>Every internationalisation-aware program makes available for translation one or more message-catalogue files. The extension of these files is <literal role="extension"
>.pot</literal
>. <acronym
>POT</acronym
> is an acronym for <quote
>Portable Object Template</quote
>.</para>


<para
>Every translator takes a <acronym
>POT</acronym
> file copy and begins translating messages. This file will became a <acronym
>PO</acronym
> file - Portable Object and represents only one language.</para>

<para
>Each translator takes a copy of one of these POT templates and begins filling in the blanks: each message is translated into the language desired. The file containing the translated text is referred to as a <acronym
>PO</acronym
> (Portable Object) file. </para>

<para
>Once all the messages have been translated, the <acronym
>PO</acronym
> file is compiled into a machine-readable binary format, known as a <acronym
>MO</acronym
> (Machine Object) file. These files, which will be stored with a <literal role="extension"
>.mo</literal
> extension, act as a database to minimise the time taken by the applications to look up each translated message. </para>

<para
>This suggests a question: do I need to know what is inside a <acronym
>PO</acronym
> file even though I have &kbabel;? The answer is, undoubtedly, yes. There are situations when a message catalogue can become corrupted and needs to be manually fixed. Most of these problems are the so-hated <acronym
>CVS</acronym
> conflicts which occur when a translating process is coordinated by a concurrent version system (see the <ulink url="info:/cvs"
>CVS</ulink
> documentation). &kbabel; can't help you very much if a problem like this arises so a text editor and some knowledge of <acronym
>PO</acronym
>-files are needed. Let's see how a <acronym
>PO</acronym
> file is made.</para>

<para
><acronym
>PO</acronym
> files consist of pairs of messages&mdash;a <emphasis
>msgid</emphasis
> and a <emphasis
>msgstr</emphasis
>. The msgid is the text in English and the msgstr is the text translated into the appropriate language. The text that accompanies each msgid and msgstr is enclosed within C-like double quotes. An example, taken from a <acronym
>PO</acronym
> file for &noatun;, is <literal
>msgid &quot;Open a Playlist&quot;</literal
> </para>

<para
>Empty lines and those starting with <literal
>#</literal
> are ignored. Lines starting with a # represent comments and are a useful means of providing a note detailing which file this message is going to be used in and, in the case of the application writers, to provide additional comments to aide translation. &kbabel; displays these comment lines for every message.</para>

<para
>In many cases the first msgid-msgstr pair in <acronym
>PO</acronym
> file is a fake entry (acting as <acronym
>PO</acronym
> file header) that contains various information about the translated <acronym
>PO</acronym
> file, such as the application name, translating date, translator name and so on.</para>

<para
>Recent versions of <application
>&GNU; gettext</application
> added another useful i18n feature called <emphasis
>plural forms</emphasis
>. English uses only singular and one plural form of nouns, &eg; <quote
>1 file </quote
> and <quote
>10 files</quote
>. This leads many developers to an idea that the world is that simple and they can use messages like <quote
>Do you want to delete %1 file(s)?</quote
>, where <literal
>%1</literal
> denotes a number of files to be deleted. But this is fundamentally wrong. For Slovak translation you need 3 different forms of the message. This number is different for different languages and even when it is the same, &eg; Czech uses 3 forms as well, the rule to decide which form to use can be very different. </para>
<para
>Plural forms in <acronym
>PO</acronym
> files are here to help. Unfortunately, &kde; developers do not like the plural forms implementation in <application
>&GNU; gettext</application
> and they have introduced their own format and handling for them. </para>
</sect1>

<sect1 id="using-editor">
<title
>Editor</title>

<para
>Here is a screenshot of &kbabel;. For convenience &kbabel; has toolbars to speed up many operations and, for busy users, there are many keyboard shortcuts. The main window is divided into four parts.</para>

<para
>The <emphasis
>upper-left</emphasis
> edit box is read-only and contains the current msgid field from the opened PO-file and its English text.</para>

<para
>The <emphasis
>bottom-left</emphasis
> edit box contains the msgstr field related to the msgid shown and here you can edit the translated text.</para>

<para
>The <emphasis
>top-right</emphasis
> part of the window is a comments panel where you can view the comments added for entry currently being edited.</para>

<para
>It can be used:</para>

<itemizedlist>
<listitem
><para
>to find out how the current message is treated by the application (c-formatted or simple) </para
></listitem>
<listitem
><para
>in some cases, to read helpful comments added by the application's developer to assist the translators in their work&mdash;for example, there may be technical hints (used to great effect in the <application
>LyX</application
> project) </para
></listitem>
<listitem
><para
>when you need to know which file a message is from because you want to report a spelling mistake in the original English string. </para
></listitem>
</itemizedlist>

<screenshot>
<screeninfo
>Screenshot of &kbabel;</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="snap1.png" format="PNG"/>
</imageobject>
<textobject
><phrase
>Screenshot of &kbabel;</phrase
></textobject>
</mediaobject>
</screenshot>

<para
>The editor window (in the bottom right) is the most sophisticated part of &kbabel;'s main window. Its size can be adjusted using the splitter line between it and the comment panel (the panel in the top right). The editor window has two tabbed panels&mdash;one storing search information, the other context information. The context information tab contain a scrolled view which shows the previous and next 4 entries associated with the current entry&mdash;essentially it's a small 'snapshot' of the PO file. While translating, it is very common for message strings to be related to subsequent and previous messages, so the context panel is useful for looking at the nearby messages to get a hint as to how the current message can best be translated. Dialogue interface translation is a good example, or widgets with their associated text and "what's this" message. </para>

<sect2 id="more-kbabel-features">
<title
>More &kbabel; Features</title>

<para
>Each msgid entry can be in three states: </para>

<variablelist>
   <varlistentry>
     <term
>untranslated</term>
     <listitem>
       <para
>there is no translated text currently associated with the msgstr </para>
     </listitem>
   </varlistentry>
   <varlistentry>
      <term
>fuzzy</term>
      <listitem>
         <para
><command
>msgmerge</command
> has tried to match a translated string by looking in rest of PO-file entries. This does not work perfectly and you must edit the translated text to fit the current English text. </para>
      </listitem>
   </varlistentry>
   <varlistentry>
      <term
>translated</term>
      <listitem>
         <para
>the msgid is the completed translated form of the msgstr </para>
      </listitem>
   </varlistentry>
</variablelist>

<para
>The state of the current entry is indicated by two <acronym
>LED</acronym
>s. Depending on your configuration these can either be in the status bar or above the <guilabel
>translated string</guilabel
> edit box. Both have a customisable colour (to reflect your visual requirements or taste). Please read the <link linkend="preferences"
>Preferences</link
> section to see how you can adjust these settings.</para>

</sect2>

</sect1>

<sect1 id="kbabel-features">
<title
>Advanced Translation</title>

<para
>Now you have an idea how to translate a PO-file. In this section we will follow the standard way of translating a new PO-file using the advanced features of &kbabel;. We assume you have already opened a template POT-file and saved it as a PO file. </para>

<sect2 id="kbabel-navigation">
<title
>Navigation in PO-file</title>
<para
>&kbabel; allows you to easily navigate through the file according to the state of their translation. The untranslated/fuzzy status was introduced already. A message can be marked as erroneous as a result of <link linkend="kbabel-validation"
>validation checking</link
> or validation done by <command
>msgfmt</command
>. And, of course, &kbabel; supports browsing the history of visited messages with <guilabel
>Forward</guilabel
>/<guilabel
>Back</guilabel
>, like in &konqueror;.</para>
<para
>All commands for navigation are in <menuchoice
><guimenu
>Go</guimenu
></menuchoice
> menu. </para>
<informaltable>
<tgroup cols="2">
<tbody>

<row>
<entry
><para
><keycombo action="simul"
><keycap
>Page Up</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the previous message </para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
><keycap
>Page Down</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the next message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Ctrl;<keycap
>Page Up</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the previous fuzzy message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Ctrl;<keycap
>Page Down</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the next fuzzy message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Alt;<keycap
>Page Up</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the previous untranslated message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Alt;<keycap
>Page Down</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the next untranslated message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Shift;<keycap
>Page Up</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the previous error message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Shift;<keycap
>Page Down</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the next error message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Ctrl;&Shift;<keycap
>Page Up</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the previous fuzzy or untranslated message</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Ctrl;&Shift;<keycap
>Page Down</keycap
></keycombo
></para
></entry>
<entry
><para
>Move to the next fuzzy or untranslated message</para
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>

<sect2 id="kbabel-cleveredit">
<title
>Clever editing</title>
<para
><emphasis
>Clever editing</emphasis
> means that the editor will help you easily edit the translation while taking into account specials of the PO format. It will correctly <quote
>escape</quote
> as necessary.</para>
<para
>It also supports more than one mode for inserting end of the line. This is very useful because of the way gettext handles end of the lines. It simply ignores them. (You can imagine that all the text in <acronym
>msgstr</acronym
> is a single line.) If you want insert a <quote
>real</quote
> end of the line, you need to insert <userinput
>\n</userinput
>. But most of translators do not realize, that a new line in <acronym
>msgstr</acronym
> does not add any space between the lines. This can be easily solved by adding a space at the end of every line. But you can easily forget, so clever editing does this automatically for you. </para>
<para
>The table below summarises clever editing features. </para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
><para
><keycombo action="simul"
><keycap
>Tab</keycap
></keycombo
></para
></entry>
<entry
><para
>Insert <emphasis
>\t</emphasis
></para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
><keycap
>"</keycap
></keycombo
></para
></entry>
<entry
><para
>Insert <emphasis
>\"</emphasis
></para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
><keycap
>Enter</keycap
></keycombo
></para
></entry>
<entry
><para
>If the last character before cursor is not a space, insert one space. Then start a new line.</para
></entry>
</row
><row>
<entry
><para
><keycombo action="simul"
>&Ctrl;<keycap
>Enter</keycap
></keycombo
></para
></entry>
<entry
><para
>Start a new line without any additional logic</para
></entry>
</row>
<row>
<entry
><para
><keycombo action="simul"
>&Shift;<keycap
>Enter</keycap
></keycombo
></para
></entry>
<entry
><para
>Insert <emphasis
>\n</emphasis
> and start a new line</para
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para
>If you want to see where are spaces, you can turn on <guibutton
>Highlight background</guibutton
> and/or <guibutton
>Mark whitespaces with points</guibutton
> in preferences dialogue on tab <guilabel
>Edit</guilabel
> <guilabel
>Appearance</guilabel
>. </para>
</note>
</sect2>

<sect2 id="kbabel-roughtranslation">
<title
>Automatic translation</title>
<para
>As the first step when starting a new translation, &kbabel; provides a function for automatic filling of the messages translations by the older translations. Choose <menuchoice
><guimenu
>Tools</guimenu
><guimenuitem
>Rough Translation</guimenuitem
> </menuchoice
> and &kbabel; will present the following dialogue: </para>
<para>
<screenshot>
<screeninfo
>Rough translation dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="roughtranslation.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
<para
>In the dialogue, you should specify what to translate and choose the sources for the old translations. </para>
<para
>At the top of the <guilabel
>What to translate</guilabel
> frame are three checkboxes (<guilabel
>Untranslated entries</guilabel
>, <guilabel
>Fuzzy entries </guilabel
>, <guilabel
>Translated entries</guilabel
>) for specifying the kind of messages you want to translate. Untranslated and fuzzy entries are natural choices for automatic translation, but you can change already translated messages as well. </para>
<para
>The exact matching for <acronym
>msgid</acronym
>s will always be used for rough translation. However, you can add more strategies, &ie; <guilabel
>Allow fuzzy translation (slow)</guilabel
> and <guilabel
>Allow single word translation</guilabel
>. Both of these additional strategies must be supported by the sources used (see below). There is no specification, what does <quote
>fuzzy translation</quote
> mean, but the purpose is quite obvious. <quote
>Single word translation</quote
> is suitable for only some of the languages. &kbabel; will try to translate each word in <acronym
>msgid</acronym
> separately and then put the translated words (or phrases) in the same order in <acronym
>msgstr </acronym
>. </para>
<para
>As a source for rough translation, any dictionary module available can be used. There is a list of <guilabel
>Don't use</guilabel
> modules and <guilabel
>Use</guilabel
> modules. Modules are used in the order in the <guilabel
>Use</guilabel
> list. First module is asked for translation. If it is not found, next module in the list is asked and so on. You can use the buttons with arrows for moving modules between the lists. Don't forget to change the order to suit your needs by <guibutton
>Move Up </guibutton
> and <guibutton
>Move Down</guibutton
> buttons. </para>
<para
>Normally &kbabel; will mark every roughly translated message as fuzzy, because it assumes that any automatic translation needs to be reviewed by a translator. If you are 100% sure that the automatic translation will be correct, or you will review all the translation anyway. <guilabel
>Mark changed entries as fuzzy</guilabel
> allows you to turn off this automatic fuzzy marking, but you will need to confirm this. </para>
<para
>If you have set all the options to suit your needs, push <guibutton
>Start </guibutton
> to automatically translate messages. You can follow the progress bar and in case, there is always the <guibutton
>Stop</guibutton
> button. </para>
</sect2>

<sect2 id="kbabel-validation">
<title
>Validate your translation</title>
<para
>Everyone makes mistakes. So &kbabel; supports a number of checks for typical problems in translations. These checks (not syntax check) can be basically performed in two ways.</para>
<para
>Checks can be done at each change of the translated text. These are called <emphasis
>automatic</emphasis
> checks and they can be turned on in <link linkend="preferences-editor"
>the &kbabel; configuration dialogue</link
>. Automatic checking of syntax is possible at each saving of the file. </para>
<para
>The automatic checks can slow down &kbabel;. If you have a slower computer, you can turn off the automatic checks and use only the second possibility. You can invoke every kind of check from the <menuchoice
><guimenu
>Tools</guimenu
><guisubmenu
> Validation</guisubmenu
></menuchoice
>. Then the check is performed for all messages in the file and faulty ones are marked as errors. </para>
<variablelist>
   <varlistentry>
     <term
><guimenuitem
>Check Syntax</guimenuitem
></term>
     <listitem>
       <para
>This invokes <command
>msgfmt</command
> to check validity of the PO file as seen by gettext package. It will show the result of the command and mark error <acronym
>msgstr</acronym
>s. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Arguments</guimenuitem
></term>
     <listitem>
       <para
>Incorrect translations can crash the application. The most dangerous parts of translation are arguments, &eg; for printf-like functions. This check compares the number and types of the arguments in <acronym
>msgid</acronym
> and <acronym
>msgstr</acronym
>. They must match. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Accelerators</guimenuitem
></term>
     <listitem>
     <para
>&GUI; text commonly contain accelerators, &ie; letters which can be used for fast access to &GUI; elements by keyboard. They are denoted by special character, &eg; &amp; in &kde;. Typical requirement of the translation is that translated text should contain accelerator as well. This check will notice this problem for you. The accelerator character can be specified in <guilabel
>Preferences</guilabel
> on <guilabel
>Misc</guilabel
> tab. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Look for Translated Context Info</guimenuitem
></term>
     <listitem>
     <para
>You will probably need this only for &kde; translation. Some of the text are too common and they need to be translated differently in different contexts. In &kde; the context is described at the beginning of <acronym
>msgid</acronym
> after the special sequence <userinput
>:_</userinput
>. But if some translators are not aware of this convention and they try to translate context information as well. This check will try to find these. If the check founds translated context information, you should remove it. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Plural Forms</guimenuitem
></term>
     <listitem>
       <para
>If the <acronym
>msgid</acronym
> is specified as a <quote
>plural form</quote
>, the translation has to contain the correct number of translations separated by <userinput
>\n</userinput
>. The correct number depends on the language of translation and is specified on <guilabel
>Identity</guilabel
> tab in <guilabel
> Preferences</guilabel
> dialogue. This is implemented only for &kde; at the moment. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Equations</guimenuitem
></term>
     <listitem>
       <para
>Equations are special format of <acronym
>msgid</acronym
> typically used in .desktop files. And because your translations will be merged back to these files, <acronym
>msgstr</acronym
> must use this special format as well. This means that the translation must start (up to the first occurrence of <literal
>=</literal
> with the same text as the original message, &eg; <userinput
>Name=</userinput
>. </para>
     </listitem>
   </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-spellcheck">
<title
>Spellchecking the translation</title>
<para
>As always, it is very important to spell-check your translation before using your result. This way you can find typos and other problems in your translation. &kbabel; uses the standard &kde; library for spellchecking and its standard settings can be found in <link linkend="preferences-spellcheck"
>the &kbabel; configuration dialogue</link
>. Spell checking itself can be found in <menuchoice
><guimenu
>Tools</guimenu
><guisubmenu
>Spelling</guisubmenu
> </menuchoice
> submenu. You can use a number of modes for spell checking: </para>
<variablelist>
   <varlistentry>
     <term
><guimenuitem
>Spell check...</guimenuitem
></term>
     <listitem>
       <para
>This is a generic invocation of a dialogue where you can choose the spellchecking mode and set the default mode. This is invoked by pressing <keycombo action="simul"
>&Ctrl;<keycap
>I</keycap
> </keycombo
>. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check All...</guimenuitem
></term>
     <listitem>
       <para
>Spellcheck all messages in the file. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check from Cursor Position...</guimenuitem
></term>
     <listitem>
       <para
>Start spellchecking at the position in the current message and progress towards the end of the file. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Current...</guimenuitem
></term>
     <listitem>
       <para
>Spellcheck the current message only. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
><guimenuitem
>Check Selected Text...</guimenuitem
></term>
     <listitem>
       <para
>If there is a selected text in <acronym
>msgstr</acronym
> editor, this option is available and will spellcheck this text only. </para>
     </listitem>
   </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-tags">
<title
>Translating &XML;, <acronym
>HTML</acronym
>, ...</title>
<para
>Markup languages are used more and more in &GUI;. &kde; project also uses <acronym
>PO</acronym
>-files for translating DocBook documentation files (which is also a markup language). &kbabel; contains quite a lot of functionality to support this trend. </para>
<note>
<para
>Here, we will describe only functions related to tags used for markup itself. The other problem introduced by using markup languages is translation of longer texts. This issue is addressed by the <emphasis
>diff</emphasis
> feature described in <link linkend="kbabel-diff"
>the following section</link
>. </para>
</note>
<para
>The current version of &kbabel; is capable to find out which tags are used in <acronym
>msgid</acronym
> and provide an easy access to them using following actions from the <guimenu
>Edit</guimenu
>: </para>

<variablelist>
<varlistentry>
    <term>
        <guimenuitem
>Insert Next Tag</guimenuitem>
    </term>
    <listitem>
      <para>
        <action
>This inserts next tag found in msgid to the translation. &kbabel; finds the tag to be inserted by counting the number of tags from the beginning of the translation. </action>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <menuchoice
><guimenu
>Edit</guimenu
> <guisubmenu
>Insert Tag</guisubmenu
> </menuchoice>
    </term>
    <listitem>
      <para>
        <action
>This submenu contains all different markup tags found in original english string. By selecting a tag you can insert it at the current position of cursor in translated text. translation. </action>
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2 id="kbabel-diff">
<title
>Showing the difference</title>
<para
>As explained already, current applications, trying to be user friendly, contain a lot of longer descriptive texts, including markup. If a developer changes a part of the text, the &GNU; gettext system will, in the best case, retain the old translation and mark it as fuzzy. (In the worst case you will lose the translation completely, depending on the size of the text changes). This works OK, if a <acronym
>msgid</acronym
> is short, because then you can find the changes quickly. But if the text is long enough, you will struggle to find out what has been changed (For example, it can be only an article change by proof-reading team.) </para>
<para
>To help, &kbabel; can be asked to lookup the original <acronym
>msgid</acronym
> and to show the difference. The changes are graphically displayed in the <guilabel
>Original String</guilabel
> window. The exact method can be set in the <link linkend="preferences-editor-appearance"
>&kbabel; configuration dialogue</link
>. <menuchoice
><guimenu
>Tools</guimenu
> <guisubmenu
>Diff</guisubmenu
> <guimenuitem
>Show Diff</guimenuitem
> </menuchoice
> will show the differences found. To see the current text without the mixture of original text and differences, use <menuchoice
><guimenu
>Tools</guimenu
> <guisubmenu
>Diff</guisubmenu
> <guimenuitem
>Show Original Text</guimenuitem
> </menuchoice
>. </para>
<para
>You can turn automatic lookup of difference on and off by choosing <menuchoice
><guimenu
>Tools</guimenu
> <guisubmenu
>Diff</guisubmenu
> <guimenuitem
>Diff Mode</guimenuitem
> </menuchoice
>. When the diff mode is on, difference searching starts when you go to another message. </para>
<para
>As always, you can use different sources for finding the old version of the text, all being set in in <link linkend="preferences-diffmode"
>&kbabel; configuration dialogue</link
>: </para>
<variablelist>
   <varlistentry>
     <term
>Translation Database</term>
     <listitem>
       <para
>You can use Translation Database for difference lookup. We strongly recommend to turn on the automatic storing of the newly translated messages into Translation Database in <link linkend="database-fill"
> Translation Database configuration dialogue</link
>. This mode can be turned on by <guilabel
>Use messages from Translation Database</guilabel
>. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
>Tree of the old files</term>
     <listitem>
       <para
>This will be used only if searching in Translation Database is turned off. By setting <guilabel
>Base folder for diff files</guilabel
> you can navigate &kbabel;, which file to use for difference. It takes the relative path of the opened file and uses this relative path in the folder specified here. If there is a corresponding file, it will be used. To use this mode, you should make a copy of old files before each update. </para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term
>Manually chosen file</term>
     <listitem>
       <para
>If the previous possibility does not work, correctly, you can always set the difference file manually by choosing <menuchoice
> <guimenu
>Tools</guimenu
><guisubmenu
>Diff</guisubmenu
> <guimenuitem
>Open File for Diff</guimenuitem
></menuchoice
>. </para>
     </listitem>
   </varlistentry>
</variablelist>
<note>
<para
>The difference lookup is not always accurate, because the <acronym
>PO</acronym
>-file does not contain any reference to the original message. </para>
</note>
</sect2>

</sect1>

<sect1 id="kbabel-pluralforms">
<title
>Plural Forms</title>
<para
>Because plural forms are quite a complicated issue, we devote a special section for their suport in &kbabel;. </para>
<para
>&kbabel; can read the &GNU; plural forms only, but cannot edit them. It only supports the &kde; version of plural forms at the moment. </para>
<para
>Every language to which &kde; is translated must have set a correct number of plural forms. This is done by translating an entry in <filename
>tdelibs.po</filename
>. The number is set by selecting the name of a language, which uses the same number and <emphasis
>rules</emphasis
> for finding the right plural form. The up-to-date list of possible values can be found in the tdelibs source code, in the file <filename
>tdecore/tdelocale.cpp</filename
>. </para>
<para
>&kde; plural forms are denoted by comment <userinput
>_:</userinput
> containing the <literal
>%n</literal
> argument. This argument is then used in the message itself and it controls which plural form of your language should be used depending on the rules for your language. </para>
<para
>The translation of a plural form message has to have a special format. It must contain the correct number of translations (one for each plural form) separated by an end of the line <literal
>\n</literal
>. For example, <quote
>Selected %n files</quote
> translated to Slovak would be: </para>
<programlisting
>Vybraný %n súbor\n
Vybrané %n súbory\n
Vybraných %n súborov
</programlisting>
<para
>To check if your translation contains the correct number of plural forms, use the <menuchoice
><guimenu
>Tools</guimenu
> <guisubmenu
>Validation </guisubmenu
> <guimenuitem
>Check Plural Forms (KDE only)</guimenuitem
> </menuchoice
> menu. </para>
</sect1>
</chapter>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab 
-->