| blob | 02974e8a32383f40bc3f88a96f3e4888b92e9461 |
1 <HTML>
2 <HEAD>
3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 6 June 2010 -->
8 </HEAD>
9 <BODY>
10 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_7.html">previous</A>, <A HREF="gettext_9.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
11 <P><HR><P>
15 <P>
18 </P>
23 <P>
26 </P>
30 <P>
33 </P>
37 <P>
40 </P>
42 <P>
43 For those of you being
44 the lucky users of Emacs, PO mode has been specifically created
45 for providing a cozy environment for editing or modifying PO files.
46 While editing a PO file, PO mode allows for the easy browsing of
47 auxiliary and compendium PO files, as well as for following references into
48 the set of C program sources from which PO files have been derived.
49 It has a few special features, among which are the interactive marking
50 of program strings as translatable, and the validation of PO files
51 with easy repositioning to PO file lines showing errors.
53 </P>
54 <P>
55 For the beginning, besides main PO mode commands
56 (see section <A HREF="gettext_8.html#SEC60">8.3.2 Main PO mode Commands</A>), you should know how to move between entries
57 (see section <A HREF="gettext_8.html#SEC61">8.3.3 Entry Positioning</A>), and how to handle untranslated entries
60 </P>
64 <H3><A NAME="SEC59" HREF="gettext_toc.html#TOC59">8.3.1 Completing GNU <CODE>gettext</CODE> Installation</A></H3>
66 <P>
69 Once you have received, unpacked, configured and compiled the GNU
73 top off a comfortable installation, you might also want to make the
74 PO mode available to your Emacs users.
76 </P>
77 <P>
80 During the installation of the PO mode, you might want to modify your
82 like:
84 </P>
86 <PRE>
87 (setq auto-mode-alist
88 (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist))
90 </PRE>
92 <P>
95 Emacs loads <TT>‘po-mode.elc’</TT> (or <TT>‘po-mode.el’</TT>) as needed, and
96 automatically activates PO mode commands for the associated buffer.
98 which PO mode is active. Many PO files may be active at once in a
99 single Emacs session.
101 </P>
102 <P>
103 If you are using Emacs version 20 or newer, and have already installed
104 the appropriate international fonts on your system, you may also tell
105 Emacs how to determine automatically the coding system of every PO file.
106 This will often (but not always) cause the necessary fonts to be loaded
107 and used for displaying the translations on your Emacs screen. For this
108 to happen, add the lines:
110 </P>
112 <PRE>
113 (modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\."
114 'po-find-file-coding-system)
115 (autoload 'po-find-file-coding-system "po-mode")
116 </PRE>
118 <P>
120 of international characters, try a different font set (via Shift Mouse
121 button 1).
123 </P>
128 <P>
131 After setting up Emacs with something similar to the lines in
132 section <A HREF="gettext_8.html#SEC59">8.3.1 Completing GNU <CODE>gettext</CODE> Installation</A>, PO mode is activated for a window when Emacs finds a
133 PO file in that window. This puts the window read-only and establishes a
134 po-mode-map, which is a genuine Emacs mode, in a way that is not derived
136 if any, will be executed.
138 </P>
139 <P>
141 in the mode line for that window. The mode line also displays how
142 many entries of each kind are held in the PO file. For example,
144 PO mode contains 132 translated entries (see section <A HREF="gettext_8.html#SEC63">8.3.5 Translated Entries</A>,
145 3 fuzzy entries (see section <A HREF="gettext_8.html#SEC64">8.3.6 Fuzzy Entries</A>), 10 untranslated entries
146 (see section <A HREF="gettext_8.html#SEC65">8.3.7 Untranslated Entries</A>) and 2 obsolete entries (see section <A HREF="gettext_8.html#SEC66">8.3.8 Obsolete Entries</A>). Zero-coefficients items are not shown. So, in this example, if
147 the fuzzy entries were unfuzzied, the untranslated entries were translated
148 and the obsolete entries were deleted, the mode line would merely display
151 </P>
152 <P>
153 The main PO commands are those which do not fit into the other categories of
154 subsequent sections. These allow for quitting PO mode or for managing windows
155 in special ways.
157 </P>
161 <DD>
166 <DD>
171 <DD>
176 <DD>
181 <DD>
183 <DD>
189 <DD>
194 <DD>
198 </DL>
200 <P>
204 <EM>undo</EM> facility. See section ‘Undoing Changes’ in <CITE>The Emacs Editor</CITE>. Each time <KBD>_</KBD> is typed, modifications which the translator
205 did to the PO file are undone a little more. For the purpose of
206 undoing, each PO mode command is atomic. This is especially true for
208 use of this command is undone at once, even if the edition itself
209 implied several actions. However, while in the editing window, one
210 can undo the edition work quite parsimoniously.
212 </P>
213 <P>
220 PO file. The former is a bit less verbose than the latter. If the file
221 has been modified, it is saved to disk first. In both cases, and prior to
222 all this, the commands check if any untranslated messages remain in the
223 PO file and, if so, the translator is asked if she really wants to leave
224 off working with this PO file. This is the preferred way of getting rid
225 of an Emacs PO file buffer. Merely killing it through the usual command
228 </P>
229 <P>
233 to leave PO mode, temporarily. It just moves the cursor to some other
234 Emacs window, and pops one if necessary. For example, if the translator
235 just got PO mode to show some source context in some other, she might
236 discover some apparent bug in the program source that needs correction.
237 This command allows the translator to change sex, become a programmer,
238 and have the cursor right into the window containing the program she
240 in the PO file window, or by asking Emacs to edit this file once again,
241 PO mode is then recovered.
243 </P>
244 <P>
249 mode commands. The translator should then type any character to resume
253 </P>
254 <P>
258 entries in the PO file, the ordinal of the current entry (counted from
259 1), the number of untranslated entries, the number of obsolete entries,
260 and displays all these numbers.
262 </P>
263 <P>
267 checking and verbose
268 mode over the current PO file. This command first offers to save the
270 has the purpose of creating a MO file out of a PO file, and PO mode uses
271 the features of this program for checking the overall format of a PO file,
272 as well as all individual entries.
274 </P>
275 <P>
278 translator regains control immediately while her PO file is being studied.
282 translator to reposition quickly to the offending parts of the PO file.
283 Once the cursor is on the line in error, the translator may decide on
284 any PO mode action which would help correcting the error.
286 </P>
291 <P>
293 The cursor in a PO file window is almost always part of
294 an entry. The only exceptions are the special case when the cursor
295 is after the last entry in the file, or when the PO file is
296 empty. The entry where the cursor is found to be is said to be the
297 current entry. Many PO mode commands operate on the current entry,
298 so moving the cursor does more than allowing the translator to browse
299 the PO file, this also selects on which entry commands operate.
301 </P>
302 <P>
304 Some PO mode commands alter the position of the cursor in a specialized
305 way. A few of those special purpose positioning are described here,
306 the others are described in following sections (for a complete list try
309 </P>
313 <DD>
318 <DD>
323 <DD>
328 <DD>
333 <DD>
338 <DD>
340 Record the location of the current entry for later use
344 <DD>
349 <DD>
351 Exchange the current entry location with the previously saved one
354 </DL>
356 <P>
359 Any Emacs command able to reposition the cursor may be used
360 to select the current entry in PO mode, including commands which
361 move by characters, lines, paragraphs, screens or pages, and search
362 commands. However, there is a kind of standard way to display the
363 current entry in PO mode, which usual Emacs commands moving
366 current entry properly, after the current entry has been changed by
367 means external to PO mode, or the Emacs screen otherwise altered.
369 </P>
370 <P>
371 It is yet to be decided if PO mode helps the translator, or otherwise
372 irritates her, by forcing a rigid window disposition while she
373 is doing her work. We originally had quite precise ideas about
374 how windows should behave, but on the other hand, anyone used to
375 Emacs is often happy to keep full control. Maybe a fixed window
376 disposition might be offered as a PO mode option that the translator
377 might activate or deactivate at will, so it could be offered on an
378 experimental basis. If nobody feels a real need for using it, or
379 a compulsion for writing it, we should drop this whole idea.
380 The incentive for doing it should come from translators rather than
381 programmers, as opinions from an experienced translator are surely
385 </P>
386 <P>
395 is given while the cursor is on the first entry, no move is done.
397 </P>
398 <P>
405 entry, of the PO file. When the cursor is located past the last
406 entry in a PO file, most PO mode commands will return an error saying
407 <SAMP>‘After last entry’</SAMP>. Moreover, the commands <KBD><</KBD> and <KBD>></KBD>
408 have the special property of being able to work even when the cursor
409 is not into some PO file entry, and one may use them for nicely
410 correcting this situation. But even these commands will fail on a
411 truly empty PO file. There are development plans for the PO mode for it
412 to interactively fill an empty PO file from sources. See section <A HREF="gettext_4.html#SEC21">4.5 Marking Translatable Strings</A>.
414 </P>
415 <P>
416 The translator may decide, before working at the translation of
417 a particular entry, that she needs to browse the remainder of the
418 PO file, maybe for finding the terminology or phraseology used
419 in related entries. She can of course use the standard Emacs idioms
420 for saving the current cursor location in some register, and use that
421 register for getting back, or else, use the location ring.
423 </P>
424 <P>
429 PO mode offers another approach, by which cursor locations may be saved
431 merely adds the location of current entry to the stack, pushing
432 the already saved locations under the new one. The command
434 repositions the cursor to the entry associated with that top element.
436 to the previously saved location, and so on until no locations remain
437 on the stack.
439 </P>
440 <P>
441 If the translator wants the position to be kept on the location stack,
442 maybe for taking a look at the entry associated with the top
443 element, then go elsewhere with the intent of getting back later, she
446 </P>
447 <P>
451 repositions the cursor to the entry associated with the top element of
452 the stack of saved locations, and replaces that top element with the
453 location of the current entry before the move. Consequently, repeating
455 For achieving this, the translator will position the cursor on the
459 </P>
463 <P>
466 </P>
467 <P>
468 There are many different ways for encoding a particular string into a
469 PO file entry, because there are so many different ways to split and
470 quote multi-line strings, and even, to represent special characters
471 by backslashed escaped sequences. Some features of PO mode rely on
472 the ability for PO mode to scan an already existing PO file for a
474 Even if PO mode has internally all the built-in machinery for
475 implementing this recognition easily, doing it fast is technically
476 difficult. To facilitate a solution to this efficiency problem,
477 we decided on a canonical representation for strings.
479 </P>
480 <P>
481 A conventional representation of strings in a PO file is currently
482 under discussion, and PO mode experiments with a canonical representation.
484 way of representing equivalent strings would be useful, as the internal
485 normalization needed by PO mode could be automatically satisfied
487 PO mode normalization should then be only necessary for PO files
488 imported from elsewhere, or for when the convention itself evolves.
490 </P>
491 <P>
492 So, for achieving normalization of at least the strings of a given
493 PO file needing a canonical representation, the following PO mode
494 command is available:
496 </P>
497 <P>
502 <DD>
504 Tidy the whole PO file by making entries more uniform.
506 </DL>
508 <P>
510 keys, revises all entries, ensuring that strings of both original
511 and translated entries use uniform internal quoting in the PO file.
512 It also removes any crumb after the last entry. This command may be
513 useful for PO files freshly imported from elsewhere, or if we ever
514 improve on the canonical quoting format we use. This canonical format
515 is not only meant for getting cleaner PO files, but also for greatly
518 </P>
519 <P>
521 The first implements heuristics for converting PO files for GNU
523 fields were using K&R style C string syntax for multi-line strings.
524 These heuristics may fail for comments not related to obsolete
525 entries and ending with a backslash; they also depend on subsequent
526 passes for finalizing the proper commenting of continued lines for
527 obsolete entries. This first pass might disappear once all oldish PO
528 files would have been adjusted. The second and third pass normalize
531 for continued lines.
533 </P>
534 <P>
536 Having such an explicit normalizing command allows for importing PO
537 files from other sources, but also eases the evolution of the current
538 convention, evolution driven mostly by aesthetic concerns, as of now.
539 It is easy to make suggested adjustments at a later time, as the
541 should greatly automate conformance. A description of the canonical
542 string format is given below, for the particular benefit of those not
543 having Emacs handy, and who would nevertheless want to handcraft
544 their PO files in nice ways.
546 </P>
547 <P>
549 Right now, in PO mode, strings are single line or multi-line. A string
553 </P>
555 <PRE>
556 msgstr "\n\nHello, world!\n\n\n"
557 </PRE>
559 <P>
560 but, replacing the space by a newline, this becomes:
562 </P>
564 <PRE>
565 msgstr ""
566 "\n"
567 "\n"
568 "Hello,\n"
569 "world!\n"
570 "\n"
571 "\n"
572 </PRE>
574 <P>
575 We are deliberately using a caricatural example, here, to make the
576 point clearer. Usually, multi-lines are not that bad looking.
577 It is probable that we will implement the following suggestion.
578 We might lump together all initial newlines into the empty string,
581 string), so making the previous example appear:
583 </P>
585 <PRE>
586 msgstr "\n\n"
587 "Hello,\n"
588 "world!\n"
589 "\n\n"
590 </PRE>
592 <P>
593 There are a few yet undecided little points about string normalization,
594 to be documented in this manual, once these questions settle.
596 </P>
600 <P>
603 </P>
604 <P>
606 a translation, and which is not marked as fuzzy (see section <A HREF="gettext_8.html#SEC64">8.3.6 Fuzzy Entries</A>),
609 Other entry types will be excluded; translation will not occur for them.
611 </P>
612 <P>
614 Some commands are more specifically related to translated entry processing.
616 </P>
620 <DD>
625 <DD>
629 </DL>
631 <P>
638 for an translated entry. If none is found, the search is extended and
639 wraps around in the PO file buffer.
641 </P>
642 <P>
644 Translated entries usually result from the translator having edited in
645 a translation for them, section <A HREF="gettext_8.html#SEC67">8.3.9 Modifying Translations</A>. However, if the
647 received a new translation first becomes a fuzzy entry, which ought to
648 be later unfuzzied before becoming an official, genuine translated entry.
651 </P>
655 <P>
658 </P>
659 <P>
663 qualities given a name and explicitly associated with the translation,
664 using a special system comment. One of these attributes
666 to have a fuzzy translation. They are called fuzzy entries, for short.
668 </P>
669 <P>
670 Fuzzy entries, even if they account for translated entries for
671 most other purposes, usually call for revision by the translator.
673 update an older translated PO files according to a new PO template
675 been modified only slightly out of an older one, and chooses to pair
676 what it thinks to be the old translation for the new modified entry.
678 should often be reflected in the translated string, and this requires
680 might mark some entries as being fuzzy.
682 </P>
683 <P>
685 Also, the translator may decide herself to mark an entry as fuzzy
686 for her own convenience, when she wants to remember that the entry
687 has to be later revisited. So, some commands are more specifically
688 related to fuzzy entry processing.
690 </P>
694 <DD>
699 <DD>
704 <DD>
708 </DL>
710 <P>
717 a fuzzy entry. If none is found, the search is extended and wraps
718 around in the PO file buffer.
720 </P>
721 <P>
726 attribute associated with an entry, usually leaving it translated.
729 for another interesting entry to work on. The initial value of
732 </P>
733 <P>
737 ensure some kind of double check, later. In this case, the usual paradigm
738 is that an entry becomes fuzzy (if not already) whenever the translator
739 modifies it. If she is satisfied with the translation, she then uses
742 to chase another entry, leaving the entry fuzzy.
744 </P>
745 <P>
750 fuzzy, when she wants to easily leave a trace she wants to later return
751 working at this entry.
753 </P>
754 <P>
756 command, the translator is asked for confirmation, if fuzzy string
757 still exists.
759 </P>
763 <P>
766 </P>
767 <P>
772 Later, when the programmer slightly modifies some string right in
773 the program, this change is later reflected in the PO file
774 by the appearance of a new untranslated entry for the modified string.
776 </P>
777 <P>
778 The usual commands moving from entry to entry consider untranslated
779 entries on the same level as active entries. Untranslated entries
782 </P>
783 <P>
785 The work of the translator might be (quite naively) seen as the process
786 of seeking for an untranslated entry, editing a translation for
787 it, and repeating these actions until no untranslated entries remain.
788 Some commands are more specifically related to untranslated entry
789 processing.
791 </P>
795 <DD>
800 <DD>
805 <DD>
809 </DL>
811 <P>
818 chasing for an untranslated entry. If none is found, the search is
819 extended and wraps around in the PO file buffer.
821 </P>
822 <P>
825 An entry can be turned back into an untranslated entry by
827 (<CODE>po-kill-msgstr</CODE>). See section <A HREF="gettext_8.html#SEC67">8.3.9 Modifying Translations</A>.
829 </P>
830 <P>
831 Also, when time comes to quit working on a PO file buffer
833 if some untranslated string still exists.
835 </P>
839 <P>
842 </P>
843 <P>
846 translation is not needed anymore by the package being localized.
848 </P>
849 <P>
850 The usual commands moving from entry to entry consider obsolete
851 entries on the same level as active entries. Obsolete entries are
852 easily recognizable by the fact that all their lines start with
855 </P>
856 <P>
857 Commands exist for emptying the translation or reinitializing it
858 to the original untranslated string. Commands interfacing with the
859 kill ring may force some previously saved text into the translation.
860 The user may interactively edit the translation. All these commands
861 may apply to obsolete entries, carefully leaving the entry obsolete
862 after the fact.
864 </P>
865 <P>
867 Moreover, some commands are more specifically related to obsolete
868 entry processing.
870 </P>
874 <DD>
879 <DD>
884 <DD>
886 Make an active entry obsolete, or zap out an obsolete entry
889 </DL>
891 <P>
898 chasing for an obsolete entry. If none is found, the search is
899 extended and wraps around in the PO file buffer.
901 </P>
902 <P>
903 PO mode does not provide ways for un-commenting an obsolete entry
904 and making it active, because this would reintroduce an original
905 untranslated string which does not correspond to any marked string
906 in the program sources. This goes with the philosophy of never
909 </P>
910 <P>
915 However, it is possible to comment out an active entry, so making
917 disappearance of a translation by using the untranslated string.
919 a little further towards annihilation. If the entry is active (it is a
920 translated entry), then it is first made fuzzy. If it is already fuzzy,
921 then the entry is merely commented out, with confirmation. If the entry
922 is already obsolete, then it is completely deleted from the PO file.
923 It is easy to recycle the translation so deleted into some other PO file
924 entry, usually one which is untranslated. See section <A HREF="gettext_8.html#SEC67">8.3.9 Modifying Translations</A>.
926 </P>
927 <P>
928 Here is a quite interesting problem to solve for later development of
929 PO mode, for those nights you are not sleepy. The idea would be that
930 PO mode might become bright enough, one of these days, to make good
931 guesses at retrieving the most probable candidate, among all obsolete
932 entries, for initializing the translation of a newly appeared string.
933 I think it might be a quite hard problem to do this algorithmically, as
934 we have to develop good and efficient measures of string similarity.
935 Right now, PO mode completely lets the decision to the translator,
936 when the time comes to find the adequate obsolete translation, it
937 merely tries to provide handy tools for helping her to do so.
939 </P>
943 <P>
947 </P>
948 <P>
949 PO mode prevents direct modification of the PO file, by the usual
950 means Emacs gives for altering a buffer's contents. By doing so,
951 it pretends helping the translator to avoid little clerical errors
952 about the overall file format, or the proper quoting of strings,
953 as those errors would be easily made. Other kinds of errors are
954 still possible, but some may be caught and diagnosed by the batch
955 validation process, which the translator may always trigger by the
957 her own judgment, and also on the linguistic reports submitted to her
958 by the users of the translated package, having the same mother tongue.
960 </P>
961 <P>
962 When the time comes to create a translation, correct an error diagnosed
963 mechanically or reported by a user, the translators have to resort to
964 using the following commands for modifying the translations.
966 </P>
970 <DD>
975 <DD>
977 <DD>
980 Reinitialize the translation with the original, untranslated string
984 <DD>
989 <DD>
991 Save the translation on the kill ring, without deleting it
995 <DD>
997 Replace the translation, taking the new from the kill ring
1000 </DL>
1002 <P>
1006 window meant to edit in a new translation, or to modify an already existing
1007 translation. The new window contains a copy of the translation taken from
1008 the current PO file entry, all ready for edition, expunged of all quoting
1009 marks, fully modifiable and with the complete extent of Emacs modifying
1010 commands. When the translator is done with her modifications, she may use
1012 results, or <KBD>C-c C-k</KBD> to abort her modifications. See section <A HREF="gettext_8.html#SEC69">8.3.11 Details of Sub Edition</A>,
1013 for more information.
1015 </P>
1016 <P>
1021 reinitializes the translation with the original string. This command is
1022 normally used when the translator wants to redo a fresh translation of
1023 the original string, disregarding any previous work.
1025 </P>
1026 <P>
1028 It is possible to arrange so, whenever editing an untranslated
1031 initialised with the original string, in case none exists already.
1034 </P>
1035 <P>
1037 In fact, whether it is best to start a translation with an empty
1038 string, or rather with a copy of the original string, is a matter of
1039 taste or habit. Sometimes, the source language and the
1040 target language are so different that is simply best to start writing
1041 on an empty page. At other times, the source and target languages
1042 are so close that it would be a waste to retype a number of words
1043 already being written in the original string. A translator may also
1044 like having the original string right under her eyes, as she will
1045 progressively overwrite the original text with the translation, even
1046 if this requires some extra editing work to get rid of the original.
1048 </P>
1049 <P>
1056 translation string, so turning the entry into an untranslated
1057 one. But while doing so, its previous contents is put apart in
1060 copy of the translation onto the kill ring, but it otherwise leaves
1062 entry. Both commands use exactly the Emacs kill ring, which is shared
1063 between buffers, and which is well known already to Emacs lovers.
1065 </P>
1066 <P>
1068 of her work, as the kill ring may hold several saved translations.
1069 From the kill ring, strings may later be reinserted in various
1070 Emacs buffers. In particular, the kill ring may be used for moving
1071 translation strings between different entries of a single PO file
1072 buffer, or if the translator is handling many such buffers at once,
1073 even between PO files.
1075 </P>
1076 <P>
1077 To facilitate exchanges with buffers which are not in PO mode, the
1079 unquoted before being saved: external quotes are removed, multi-line
1080 strings are concatenated, and backslash escaped sequences are turned
1081 into their corresponding characters. In the special case of obsolete
1082 entries, the translation is also uncommented prior to saving.
1084 </P>
1085 <P>
1089 translation of the current entry by a string taken from the kill ring.
1090 Following Emacs terminology, we then say that the replacement
1095 again, immediately, without intervening keystrokes, the translation
1096 just inserted is taken away and replaced by the second most recent
1098 the translator may travel along the kill ring for saved strings,
1099 until she finds the string she really wanted.
1101 </P>
1102 <P>
1103 When a string is yanked into a PO file entry, it is fully and
1104 automatically requoted for complying with the format PO files should
1105 have. Further, if the entry is obsolete, PO mode then appropriately
1106 push the inserted string inside comments. Once again, translators
1107 should not burden themselves with quoting considerations besides, of
1108 course, the necessity of the translated string itself respective to
1109 the program using it.
1111 </P>
1112 <P>
1114 on the kill ring, as almost any PO mode command replacing translation
1115 strings (or the translator comments) automatically saves the old string
1116 on the kill ring. The main exceptions to this general rule are the
1117 yanking commands themselves.
1119 </P>
1120 <P>
1122 To better illustrate the operation of killing and yanking, let's
1123 use an actual example, taken from a common situation. When the
1124 programmer slightly modifies some string right in the program, his
1125 change is later reflected in the PO file by the appearance
1126 of a new untranslated entry for the modified string, and the fact
1127 that the entry translating the original or unmodified string becomes
1128 obsolete. In many cases, the translator might spare herself some work
1129 by retrieving the unmodified translation from the obsolete entry,
1131 this retrieved translation. Once this done, the obsolete entry is
1132 not wanted anymore, and may be safely deleted.
1134 </P>
1135 <P>
1136 When the translator finds an untranslated entry and suspects that a
1138 to mark the current entry location, then starts chasing obsolete
1142 the translation, that is, pushes the translation on the kill ring.
1149 </P>
1150 <P>
1151 When some sequence of keys has to be typed over and over again, the
1152 translator may find it useful to become better acquainted with the Emacs
1153 capability of learning these sequences and playing them back under request.
1156 </P>
1160 <P>
1164 </P>
1165 <P>
1166 Any translation work done seriously will raise many linguistic
1167 difficulties, for which decisions have to be made, and the choices
1168 further documented. These documents may be saved within the
1169 PO file in form of translator comments, which the translator
1170 is free to create, delete, or modify at will. These comments may
1171 be useful to herself when she returns to this PO file after a while.
1173 </P>
1174 <P>
1176 those beginning with <SAMP>‘#.’</SAMP> or <SAMP>‘#:’</SAMP>, are <EM>not</EM> translator
1178 So, the commands below will never alter such system added comments,
1179 they are not meant for the translator to modify. See section <A HREF="gettext_3.html#SEC15">3 The Format of PO Files</A>.
1181 </P>
1182 <P>
1183 The following commands are somewhat similar to those modifying translations,
1184 so the general indications given for those apply here. See section <A HREF="gettext_8.html#SEC67">8.3.9 Modifying Translations</A>.
1186 </P>
1190 <DD>
1195 <DD>
1197 Save the translator comments on the kill ring, and delete it
1201 <DD>
1203 Save the translator comments on the kill ring, without deleting it
1207 <DD>
1209 Replace the translator comments, taking the new from the kill ring
1212 </DL>
1214 <P>
1215 These commands parallel PO mode commands for modifying the translation
1216 strings, and behave much the same way as they do, except that they handle
1217 this part of PO file comments meant for translator usage, rather
1218 than the translation strings. So, if the descriptions given below are
1219 slightly succinct, it is because the full details have already been given.
1222 </P>
1223 <P>
1227 containing a copy of the translator comments on the current PO file entry.
1228 If there are no such comments, PO mode understands that the translator wants
1229 to add a comment to the entry, and she is presented with an empty screen.
1231 removed before edition, and reinstated after. For translator comments
1232 pertaining to obsolete entries, the uncommenting and recommenting operations
1234 allow the translator to tell she is finished with editing the comment.
1235 See section <A HREF="gettext_8.html#SEC69">8.3.11 Details of Sub Edition</A>, for further details.
1237 </P>
1238 <P>
1241 the string has been inserted in the edit buffer.
1243 </P>
1244 <P>
1252 translator comments, while saving those comments on the kill ring.
1254 a copy of the translator comments on the kill ring, but leaves
1257 by a string taken at the front of the kill ring. When this command
1258 is immediately repeated, the comments just inserted are withdrawn,
1259 and replaced by other strings taken along the kill ring.
1261 </P>
1262 <P>
1263 On the kill ring, all strings have the same nature. There is no
1265 comments</EM> strings. So, for example, let's presume the translator
1266 has just finished editing a translation, and wants to create a new
1267 translator comment to document why the previous translation was
1268 not good, just to remember what was the problem. Foreseeing that she
1269 will do that in her documentation, the translator may want to quote
1270 the previous translation in her translator comments. To do so, she
1271 may initialize the translator comments with the previous translation,
1272 still at the head of the kill ring. Because editing already pushed the
1275 all ready for being introduced by some explanatory text.
1277 </P>
1278 <P>
1279 On the other hand, presume there are some translator comments already
1280 and that the translator wants to add to those comments, instead
1281 of wholly replacing them. Then, she should edit the comment right
1286 </P>
1290 <P>
1293 </P>
1294 <P>
1295 The PO subedit minor mode has a few peculiarities worth being described
1296 in fuller detail. It installs a few commands over the usual editing set
1297 of Emacs, which are described below.
1299 </P>
1303 <DD>
1308 <DD>
1313 <DD>
1317 </DL>
1319 <P>
1323 The window's contents represents a translation for a given message,
1324 or a translator comment. The translator may modify this window to
1327 the PO file, replacing the original translation, even if it moved out of
1328 sight or if buffers were switched.
1330 </P>
1331 <P>
1334 If the translator becomes unsatisfied with her translation or comment,
1335 to the extent she prefers keeping what was existent prior to the
1338 the original translation or comment. Another way would be for her to exit
1340 whole effect of last edition.
1342 </P>
1343 <P>
1347 allows for glancing through translations
1348 already achieved in other languages, directly while editing the current
1349 translation. This may be quite convenient when the translator is fluent
1350 at many languages, but of course, only makes sense when such completed
1351 auxiliary PO files are already available to her (see section <A HREF="gettext_8.html#SEC71">8.3.13 Consulting Auxiliary PO Files</A>).
1353 </P>
1354 <P>
1356 the string has been inserted in the edit buffer.
1358 </P>
1359 <P>
1360 While editing her translation, the translator should pay attention to not
1362 the translated string if those are not meant to be there, or to removing
1363 such characters when they are required. Since these characters are not
1364 visible in the editing buffer, they are easily introduced by mistake.
1370 looses its delimiting property and integrally becomes part of the string.
1377 </P>
1378 <P>
1380 When a translation (or a comment) is being edited, the translator may move
1381 the cursor back into the PO file buffer and freely move to other entries,
1382 browsing at will. If, with an edition pending, the translator wanders in the
1383 PO file buffer, she may decide to start modifying another entry. Each entry
1384 being edited has its own subedit buffer. It is possible to simultaneously
1387 on a field already being edited merely resumes that particular edit. Yet,
1388 the translator should better be comfortable at handling many Emacs windows!
1390 </P>
1391 <P>
1393 Pending subedits may be completed or aborted in any order, regardless
1394 of how or when they were started. When many subedits are pending and the
1396 are automatically resumed one at a time, so she may decide for each of them.
1398 </P>
1402 <P>
1407 </P>
1408 <P>
1409 PO mode is particularly powerful when used with PO files
1411 insert special comments in the PO files they generate.
1412 Some of these special comments relate the PO file entry to
1413 exactly where the untranslated string appears in the program sources.
1415 </P>
1416 <P>
1417 When the translator gets to an untranslated entry, she is fairly
1418 often faced with an original string which is not as informative as
1419 it normally should be, being succinct, cryptic, or otherwise ambiguous.
1420 Before choosing how to translate the string, she needs to understand
1421 better what the string really means and how tight the translation has
1422 to be. Most of the time, when problems arise, the only way left to make
1423 her judgment is looking at the true program sources from where this
1424 string originated, searching for surrounding comments the programmer
1425 might have put in there, and looking around for helping clues of
1428 </P>
1429 <P>
1430 Surely, when looking at program sources, the translator will receive
1431 more help if she is a fluent programmer. However, even if she is
1432 not versed in programming and feels a little lost in C code, the
1433 translator should not be shy at taking a look, once in a while.
1434 It is most probable that she will still be able to find some of the
1435 hints she needs. She will learn quickly to not feel uncomfortable
1436 in program code, paying more attention to programmer's comments,
1437 variable and function names (if he dared choosing them well), and
1438 overall organization, than to the program code itself.
1440 </P>
1441 <P>
1443 The following commands are meant to help the translator at getting
1444 program source context for a PO file entry.
1446 </P>
1450 <DD>
1452 Resume the display of a program source context, or cycle through them
1456 <DD>
1458 Display of a program source context selected by menu
1462 <DD>
1464 Add a directory to the search path for source files
1468 <DD>
1470 Delete a directory from the search path for source files
1473 </DL>
1475 <P>
1482 some source program file, and already positioned in such a way that
1483 it shows an actual use of the string to be translated. By doing
1484 so, the command gives source program context for the string. But if
1485 the entry has no source context references, or if all references
1486 are unresolved along the search path for program sources, then the
1487 command diagnoses this as an error.
1489 </P>
1490 <P>
1492 in the PO file window. If the translator really wants to
1493 get into the program source window, she ought to do it explicitly,
1496 </P>
1497 <P>
1499 is different of the last one used for getting source context, then the
1500 command reacts by giving the first context available for this entry,
1501 if any. If some context has already been recently displayed for the
1502 current PO file entry, and the translator wandered off to do other
1504 the context last displayed. In particular, if the translator moved
1505 the cursor away from the context in the source file, the command will
1507 in a row, with no other commands intervening, PO mode will cycle to
1508 the next available contexts for this particular entry, getting back
1509 to the first context once the last has been shown.
1511 </P>
1512 <P>
1514 references, it lets the translator choose a particular reference among
1515 many, and displays that reference. It is best used with completion,
1517 response to the question, she will be offered a menu of all possible
1518 references, as a reminder of which are the acceptable answers.
1519 This command is useful only where there are really many contexts
1520 available for a single string to translate.
1522 </P>
1523 <P>
1528 Program source files are usually found relative to where the PO
1529 file stands. As a special provision, when this fails, the file is
1530 also looked for, but relative to the directory immediately above it.
1531 Those two cases take proper care of most PO files. However, it might
1532 happen that a PO file has been moved, or is edited in a different
1533 place than its normal location. When this happens, the translator
1534 should tell PO mode in which directory normally sits the genuine PO
1535 file. Many such directories may be specified, and all together, they
1538 enter a new directory at the front of the search path, and the command
1540 one of the directories she does not want anymore on the search path.
1542 </P>
1545 <H3><A NAME="SEC71" HREF="gettext_toc.html#TOC71">8.3.13 Consulting Auxiliary PO Files</A></H3>
1546 <P>
1549 </P>
1550 <P>
1551 PO mode is able to help the knowledgeable translator, being fluent in
1552 many languages, at taking advantage of translations already achieved
1553 in other languages she just happens to know. It provides these other
1554 language translations as additional context for her own work. Moreover,
1555 it has features to ease the production of translations for many languages
1556 at once, for translators preferring to work in this way.
1558 </P>
1559 <P>
1563 package the translator is working on, but targeted to a different mother
1564 tongue language. Commands exist for declaring and handling auxiliary
1565 PO files, and also for showing contexts for the entry under work.
1567 </P>
1568 <P>
1569 Here are the auxiliary file commands available in PO mode.
1571 </P>
1575 <DD>
1577 Seek auxiliary files for another translation for the same entry
1581 <DD>
1586 <DD>
1591 <DD>
1593 Remove this PO file from the list of auxiliary files
1596 </DL>
1598 <P>
1607 </P>
1608 <P>
1612 files, round-robin, searching for a translated entry in some other language
1614 The found PO file, if any, takes the place of the current PO file in
1615 the display (its window gets on top). Before doing so, the current PO
1617 in this newly displayed PO file will seek another PO file, and so on,
1620 </P>
1621 <P>
1625 for her choice of a particular auxiliary file, with completion, and
1626 then switches to that selected PO file. The command also checks if
1628 the current entry, and if yes, this entry becomes current. Otherwise,
1629 the cursor of the selected file is left undisturbed.
1631 </P>
1632 <P>
1633 For all this to work fully, auxiliary PO files will have to be normalized,
1636 ways for representing the same string, different writing would break the
1637 proper behaviour of the auxiliary file commands of PO mode. This is not
1638 expected to be much a problem in practice, as most existing PO files have
1641 </P>
1642 <P>
1644 However, PO files initially created by PO mode itself, while marking
1645 strings in source files, are normalised differently. So are PO
1648 fully resolved, the translator should stay aware of normalisation issues.
1650 </P>
1654 <P>
1657 </P>
1658 <P>
1661 translations recurring in many different packages. The translator can
1662 use gettext tools to build a new compendium, to add entries to her
1663 compendium, and to initialize untranslated entries, or to update
1664 already translated entries, from translations kept in the compendium.
1666 </P>
1671 <P>
1675 </P>
1676 <P>
1677 Basically every PO file consisting of translated entries only can be
1678 declared as a valid compendium. Often the translator wants to have
1679 special compendia; let's consider two cases: <CITE>concatenating PO
1682 </P>
1687 <P>
1690 To concatenate several valid PO files into one compendium file you can
1691 use <SAMP>‘msgcomm’</SAMP> or <SAMP>‘msgcat’</SAMP> (the latter preferred):
1693 </P>
1695 <PRE>
1696 msgcat -o compendium.po file1.po file2.po
1697 </PRE>
1699 <P>
1705 </P>
1707 <PRE>
1708 #: src/hello.c:200
1709 #, c-format
1710 msgid "Report bugs to <%s>.\n"
1711 msgstr "Comunicar `bugs' a <%s>.\n"
1712 </PRE>
1714 <P>
1717 </P>
1719 <PRE>
1720 #: src/bye.c:100
1721 #, c-format
1722 msgid "Report bugs to <%s>.\n"
1724 </PRE>
1726 <P>
1727 will result in:
1729 </P>
1731 <PRE>
1733 #, fuzzy, c-format
1734 msgid "Report bugs to <%s>.\n"
1735 msgstr ""
1736 "#-#-#-#-# file1.po #-#-#-#-#\n"
1737 "Comunicar `bugs' a <%s>.\n"
1738 "#-#-#-#-# file2.po #-#-#-#-#\n"
1740 </PRE>
1742 <P>
1743 The translator will have to resolve this “conflict” manually; she
1744 has to decide whether the first or the second version is appropriate
1745 (or provide a new translation), to delete the “marker lines”, and
1748 </P>
1749 <P>
1750 If the translator knows in advance the first found translation of a
1751 message is always the best translation she can make use to the
1754 </P>
1756 <PRE>
1757 msgcat --use-first -o compendium.po file1.po file2.po
1758 </PRE>
1760 <P>
1762 entries. If input files are “dirty” you must preprocess the input
1763 files or postprocess the result using <SAMP>‘msgattrib --translated --no-fuzzy’</SAMP>.
1765 </P>
1768 <H4><A NAME="SEC75" HREF="gettext_toc.html#TOC75">8.4.1.2 Extract a Message Subset from a PO File</A></H4>
1769 <P>
1772 </P>
1773 <P>
1774 Nobody wants to translate the same messages again and again; thus you
1777 </P>
1778 <P>
1782 </P>
1784 <PRE>
1785 msggrep --location src/getopt.c -o compendium.po file.po
1786 </PRE>
1792 <P>
1793 You can use a compendium file to initialize a translation from scratch
1794 or to update an already existing translation.
1796 </P>
1799 <H4><A NAME="SEC77" HREF="gettext_toc.html#TOC77">8.4.2.1 Initialize a New Translation File</A></H4>
1800 <P>
1803 </P>
1804 <P>
1805 Since a PO file with translations does not exist the translator can
1808 </P>
1810 <PRE>
1811 msgmerge --compendium compendium.po -o file.po /dev/null file.pot
1812 </PRE>
1816 <H4><A NAME="SEC78" HREF="gettext_toc.html#TOC78">8.4.2.2 Update an Existing Translation File</A></H4>
1817 <P>
1820 </P>
1821 <P>
1822 Concatenate the compendium file(s) and the existing PO, merge the
1823 result with the POT file and remove the obsolete entries (optional,
1826 </P>
1828 <PRE>
1829 msgcat --use-first -o update.po compendium1.po compendium2.po file.po
1830 msgmerge update.po file.pot | msgattrib --no-obsolete > file.po
1831 </PRE>
1833 <P><HR><P>
1834 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_7.html">previous</A>, <A HREF="gettext_9.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
1835 </BODY>
1836 </HTML>