1*946379e7Schristos<HTML> 2*946379e7Schristos<HEAD> 3*946379e7Schristos<!-- This HTML file has been created by texi2html 1.52b 4*946379e7Schristos from gettext.texi on 27 November 2006 --> 5*946379e7Schristos 6*946379e7Schristos<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> 7*946379e7Schristos<TITLE>GNU gettext utilities - 8 Editing PO Files</TITLE> 8*946379e7Schristos</HEAD> 9*946379e7Schristos<BODY> 10*946379e7SchristosGo 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*946379e7Schristos<P><HR><P> 12*946379e7Schristos 13*946379e7Schristos 14*946379e7Schristos<H1><A NAME="SEC49" HREF="gettext_toc.html#TOC49">8 Editing PO Files</A></H1> 15*946379e7Schristos<P> 16*946379e7Schristos<A NAME="IDX301"></A> 17*946379e7Schristos 18*946379e7Schristos</P> 19*946379e7Schristos 20*946379e7Schristos 21*946379e7Schristos 22*946379e7Schristos<H2><A NAME="SEC50" HREF="gettext_toc.html#TOC50">8.1 KDE's PO File Editor</A></H2> 23*946379e7Schristos<P> 24*946379e7Schristos<A NAME="IDX302"></A> 25*946379e7Schristos 26*946379e7Schristos</P> 27*946379e7Schristos 28*946379e7Schristos 29*946379e7Schristos<H2><A NAME="SEC51" HREF="gettext_toc.html#TOC51">8.2 GNOME's PO File Editor</A></H2> 30*946379e7Schristos<P> 31*946379e7Schristos<A NAME="IDX303"></A> 32*946379e7Schristos 33*946379e7Schristos</P> 34*946379e7Schristos 35*946379e7Schristos 36*946379e7Schristos<H2><A NAME="SEC52" HREF="gettext_toc.html#TOC52">8.3 Emacs's PO File Editor</A></H2> 37*946379e7Schristos<P> 38*946379e7Schristos<A NAME="IDX304"></A> 39*946379e7Schristos 40*946379e7Schristos</P> 41*946379e7Schristos 42*946379e7Schristos<P> 43*946379e7SchristosFor those of you being 44*946379e7Schristosthe lucky users of Emacs, PO mode has been specifically created 45*946379e7Schristosfor providing a cozy environment for editing or modifying PO files. 46*946379e7SchristosWhile editing a PO file, PO mode allows for the easy browsing of 47*946379e7Schristosauxiliary and compendium PO files, as well as for following references into 48*946379e7Schristosthe set of C program sources from which PO files have been derived. 49*946379e7SchristosIt has a few special features, among which are the interactive marking 50*946379e7Schristosof program strings as translatable, and the validation of PO files 51*946379e7Schristoswith easy repositioning to PO file lines showing errors. 52*946379e7Schristos 53*946379e7Schristos</P> 54*946379e7Schristos<P> 55*946379e7SchristosFor the beginning, besides main PO mode commands 56*946379e7Schristos(see section <A HREF="gettext_8.html#SEC54">8.3.2 Main PO mode Commands</A>), you should know how to move between entries 57*946379e7Schristos(see section <A HREF="gettext_8.html#SEC55">8.3.3 Entry Positioning</A>), and how to handle untranslated entries 58*946379e7Schristos(see section <A HREF="gettext_8.html#SEC59">8.3.7 Untranslated Entries</A>). 59*946379e7Schristos 60*946379e7Schristos</P> 61*946379e7Schristos 62*946379e7Schristos 63*946379e7Schristos 64*946379e7Schristos<H3><A NAME="SEC53" HREF="gettext_toc.html#TOC53">8.3.1 Completing GNU <CODE>gettext</CODE> Installation</A></H3> 65*946379e7Schristos 66*946379e7Schristos<P> 67*946379e7Schristos<A NAME="IDX305"></A> 68*946379e7Schristos<A NAME="IDX306"></A> 69*946379e7SchristosOnce you have received, unpacked, configured and compiled the GNU 70*946379e7Schristos<CODE>gettext</CODE> distribution, the <SAMP>‘make install’</SAMP> command puts in 71*946379e7Schristosplace the programs <CODE>xgettext</CODE>, <CODE>msgfmt</CODE>, <CODE>gettext</CODE>, and 72*946379e7Schristos<CODE>msgmerge</CODE>, as well as their available message catalogs. To 73*946379e7Schristostop off a comfortable installation, you might also want to make the 74*946379e7SchristosPO mode available to your Emacs users. 75*946379e7Schristos 76*946379e7Schristos</P> 77*946379e7Schristos<P> 78*946379e7Schristos<A NAME="IDX307"></A> 79*946379e7Schristos<A NAME="IDX308"></A> 80*946379e7SchristosDuring the installation of the PO mode, you might want to modify your 81*946379e7Schristosfile <TT>‘.emacs’</TT>, once and for all, so it contains a few lines looking 82*946379e7Schristoslike: 83*946379e7Schristos 84*946379e7Schristos</P> 85*946379e7Schristos 86*946379e7Schristos<PRE> 87*946379e7Schristos(setq auto-mode-alist 88*946379e7Schristos (cons '("\\.po\\'\\|\\.po\\." . po-mode) auto-mode-alist)) 89*946379e7Schristos(autoload 'po-mode "po-mode" "Major mode for translators to edit PO files" t) 90*946379e7Schristos</PRE> 91*946379e7Schristos 92*946379e7Schristos<P> 93*946379e7SchristosLater, whenever you edit some <TT>‘.po’</TT> 94*946379e7Schristosfile, or any file having the string <SAMP>‘.po.’</SAMP> within its name, 95*946379e7SchristosEmacs loads <TT>‘po-mode.elc’</TT> (or <TT>‘po-mode.el’</TT>) as needed, and 96*946379e7Schristosautomatically activates PO mode commands for the associated buffer. 97*946379e7SchristosThe string <EM>PO</EM> appears in the mode line for any buffer for 98*946379e7Schristoswhich PO mode is active. Many PO files may be active at once in a 99*946379e7Schristossingle Emacs session. 100*946379e7Schristos 101*946379e7Schristos</P> 102*946379e7Schristos<P> 103*946379e7SchristosIf you are using Emacs version 20 or newer, and have already installed 104*946379e7Schristosthe appropriate international fonts on your system, you may also tell 105*946379e7SchristosEmacs how to determine automatically the coding system of every PO file. 106*946379e7SchristosThis will often (but not always) cause the necessary fonts to be loaded 107*946379e7Schristosand used for displaying the translations on your Emacs screen. For this 108*946379e7Schristosto happen, add the lines: 109*946379e7Schristos 110*946379e7Schristos</P> 111*946379e7Schristos 112*946379e7Schristos<PRE> 113*946379e7Schristos(modify-coding-system-alist 'file "\\.po\\'\\|\\.po\\." 114*946379e7Schristos 'po-find-file-coding-system) 115*946379e7Schristos(autoload 'po-find-file-coding-system "po-mode") 116*946379e7Schristos</PRE> 117*946379e7Schristos 118*946379e7Schristos<P> 119*946379e7Schristosto your <TT>‘.emacs’</TT> file. If, with this, you still see boxes instead 120*946379e7Schristosof international characters, try a different font set (via Shift Mouse 121*946379e7Schristosbutton 1). 122*946379e7Schristos 123*946379e7Schristos</P> 124*946379e7Schristos 125*946379e7Schristos 126*946379e7Schristos<H3><A NAME="SEC54" HREF="gettext_toc.html#TOC54">8.3.2 Main PO mode Commands</A></H3> 127*946379e7Schristos 128*946379e7Schristos<P> 129*946379e7Schristos<A NAME="IDX309"></A> 130*946379e7Schristos<A NAME="IDX310"></A> 131*946379e7SchristosAfter setting up Emacs with something similar to the lines in 132*946379e7Schristossection <A HREF="gettext_8.html#SEC53">8.3.1 Completing GNU <CODE>gettext</CODE> Installation</A>, PO mode is activated for a window when Emacs finds a 133*946379e7SchristosPO file in that window. This puts the window read-only and establishes a 134*946379e7Schristospo-mode-map, which is a genuine Emacs mode, in a way that is not derived 135*946379e7Schristosfrom text mode in any way. Functions found on <CODE>po-mode-hook</CODE>, 136*946379e7Schristosif any, will be executed. 137*946379e7Schristos 138*946379e7Schristos</P> 139*946379e7Schristos<P> 140*946379e7SchristosWhen PO mode is active in a window, the letters <SAMP>‘PO’</SAMP> appear 141*946379e7Schristosin the mode line for that window. The mode line also displays how 142*946379e7Schristosmany entries of each kind are held in the PO file. For example, 143*946379e7Schristosthe string <SAMP>‘132t+3f+10u+2o’</SAMP> would tell the translator that the 144*946379e7SchristosPO mode contains 132 translated entries (see section <A HREF="gettext_8.html#SEC57">8.3.5 Translated Entries</A>, 145*946379e7Schristos3 fuzzy entries (see section <A HREF="gettext_8.html#SEC58">8.3.6 Fuzzy Entries</A>), 10 untranslated entries 146*946379e7Schristos(see section <A HREF="gettext_8.html#SEC59">8.3.7 Untranslated Entries</A>) and 2 obsolete entries (see section <A HREF="gettext_8.html#SEC60">8.3.8 Obsolete Entries</A>). Zero-coefficients items are not shown. So, in this example, if 147*946379e7Schristosthe fuzzy entries were unfuzzied, the untranslated entries were translated 148*946379e7Schristosand the obsolete entries were deleted, the mode line would merely display 149*946379e7Schristos<SAMP>‘145t’</SAMP> for the counters. 150*946379e7Schristos 151*946379e7Schristos</P> 152*946379e7Schristos<P> 153*946379e7SchristosThe main PO commands are those which do not fit into the other categories of 154*946379e7Schristossubsequent sections. These allow for quitting PO mode or for managing windows 155*946379e7Schristosin special ways. 156*946379e7Schristos 157*946379e7Schristos</P> 158*946379e7Schristos<DL COMPACT> 159*946379e7Schristos 160*946379e7Schristos<DT><KBD>_</KBD> 161*946379e7Schristos<DD> 162*946379e7Schristos<A NAME="IDX311"></A> 163*946379e7SchristosUndo last modification to the PO file (<CODE>po-undo</CODE>). 164*946379e7Schristos 165*946379e7Schristos<DT><KBD>Q</KBD> 166*946379e7Schristos<DD> 167*946379e7Schristos<A NAME="IDX312"></A> 168*946379e7SchristosQuit processing and save the PO file (<CODE>po-quit</CODE>). 169*946379e7Schristos 170*946379e7Schristos<DT><KBD>q</KBD> 171*946379e7Schristos<DD> 172*946379e7Schristos<A NAME="IDX313"></A> 173*946379e7SchristosQuit processing, possibly after confirmation (<CODE>po-confirm-and-quit</CODE>). 174*946379e7Schristos 175*946379e7Schristos<DT><KBD>0</KBD> 176*946379e7Schristos<DD> 177*946379e7Schristos<A NAME="IDX314"></A> 178*946379e7SchristosTemporary leave the PO file window (<CODE>po-other-window</CODE>). 179*946379e7Schristos 180*946379e7Schristos<DT><KBD>?</KBD> 181*946379e7Schristos<DD> 182*946379e7Schristos<DT><KBD>h</KBD> 183*946379e7Schristos<DD> 184*946379e7Schristos<A NAME="IDX315"></A> 185*946379e7Schristos<A NAME="IDX316"></A> 186*946379e7SchristosShow help about PO mode (<CODE>po-help</CODE>). 187*946379e7Schristos 188*946379e7Schristos<DT><KBD>=</KBD> 189*946379e7Schristos<DD> 190*946379e7Schristos<A NAME="IDX317"></A> 191*946379e7SchristosGive some PO file statistics (<CODE>po-statistics</CODE>). 192*946379e7Schristos 193*946379e7Schristos<DT><KBD>V</KBD> 194*946379e7Schristos<DD> 195*946379e7Schristos<A NAME="IDX318"></A> 196*946379e7SchristosBatch validate the format of the whole PO file (<CODE>po-validate</CODE>). 197*946379e7Schristos 198*946379e7Schristos</DL> 199*946379e7Schristos 200*946379e7Schristos<P> 201*946379e7Schristos<A NAME="IDX319"></A> 202*946379e7Schristos<A NAME="IDX320"></A> 203*946379e7SchristosThe command <KBD>_</KBD> (<CODE>po-undo</CODE>) interfaces to the Emacs 204*946379e7Schristos<EM>undo</EM> facility. See section ‘Undoing Changes’ in <CITE>The Emacs Editor</CITE>. Each time <KBD>U</KBD> is typed, modifications which the translator 205*946379e7Schristosdid to the PO file are undone a little more. For the purpose of 206*946379e7Schristosundoing, each PO mode command is atomic. This is especially true for 207*946379e7Schristosthe <KBD><KBD>RET</KBD></KBD> command: the whole edition made by using a single 208*946379e7Schristosuse of this command is undone at once, even if the edition itself 209*946379e7Schristosimplied several actions. However, while in the editing window, one 210*946379e7Schristoscan undo the edition work quite parsimoniously. 211*946379e7Schristos 212*946379e7Schristos</P> 213*946379e7Schristos<P> 214*946379e7Schristos<A NAME="IDX321"></A> 215*946379e7Schristos<A NAME="IDX322"></A> 216*946379e7Schristos<A NAME="IDX323"></A> 217*946379e7Schristos<A NAME="IDX324"></A> 218*946379e7SchristosThe commands <KBD>Q</KBD> (<CODE>po-quit</CODE>) and <KBD>q</KBD> 219*946379e7Schristos(<CODE>po-confirm-and-quit</CODE>) are used when the translator is done with the 220*946379e7SchristosPO file. The former is a bit less verbose than the latter. If the file 221*946379e7Schristoshas been modified, it is saved to disk first. In both cases, and prior to 222*946379e7Schristosall this, the commands check if any untranslated messages remain in the 223*946379e7SchristosPO file and, if so, the translator is asked if she really wants to leave 224*946379e7Schristosoff working with this PO file. This is the preferred way of getting rid 225*946379e7Schristosof an Emacs PO file buffer. Merely killing it through the usual command 226*946379e7Schristos<KBD>C-x k</KBD> (<CODE>kill-buffer</CODE>) is not the tidiest way to proceed. 227*946379e7Schristos 228*946379e7Schristos</P> 229*946379e7Schristos<P> 230*946379e7Schristos<A NAME="IDX325"></A> 231*946379e7Schristos<A NAME="IDX326"></A> 232*946379e7SchristosThe command <KBD>0</KBD> (<CODE>po-other-window</CODE>) is another, softer way, 233*946379e7Schristosto leave PO mode, temporarily. It just moves the cursor to some other 234*946379e7SchristosEmacs window, and pops one if necessary. For example, if the translator 235*946379e7Schristosjust got PO mode to show some source context in some other, she might 236*946379e7Schristosdiscover some apparent bug in the program source that needs correction. 237*946379e7SchristosThis command allows the translator to change sex, become a programmer, 238*946379e7Schristosand have the cursor right into the window containing the program she 239*946379e7Schristos(or rather <EM>he</EM>) wants to modify. By later getting the cursor back 240*946379e7Schristosin the PO file window, or by asking Emacs to edit this file once again, 241*946379e7SchristosPO mode is then recovered. 242*946379e7Schristos 243*946379e7Schristos</P> 244*946379e7Schristos<P> 245*946379e7Schristos<A NAME="IDX327"></A> 246*946379e7Schristos<A NAME="IDX328"></A> 247*946379e7Schristos<A NAME="IDX329"></A> 248*946379e7SchristosThe command <KBD>h</KBD> (<CODE>po-help</CODE>) displays a summary of all available PO 249*946379e7Schristosmode commands. The translator should then type any character to resume 250*946379e7Schristosnormal PO mode operations. The command <KBD>?</KBD> has the same effect 251*946379e7Schristosas <KBD>h</KBD>. 252*946379e7Schristos 253*946379e7Schristos</P> 254*946379e7Schristos<P> 255*946379e7Schristos<A NAME="IDX330"></A> 256*946379e7Schristos<A NAME="IDX331"></A> 257*946379e7SchristosThe command <KBD>=</KBD> (<CODE>po-statistics</CODE>) computes the total number of 258*946379e7Schristosentries in the PO file, the ordinal of the current entry (counted from 259*946379e7Schristos1), the number of untranslated entries, the number of obsolete entries, 260*946379e7Schristosand displays all these numbers. 261*946379e7Schristos 262*946379e7Schristos</P> 263*946379e7Schristos<P> 264*946379e7Schristos<A NAME="IDX332"></A> 265*946379e7Schristos<A NAME="IDX333"></A> 266*946379e7SchristosThe command <KBD>V</KBD> (<CODE>po-validate</CODE>) launches <CODE>msgfmt</CODE> in 267*946379e7Schristoschecking and verbose 268*946379e7Schristosmode over the current PO file. This command first offers to save the 269*946379e7Schristoscurrent PO file on disk. The <CODE>msgfmt</CODE> tool, from GNU <CODE>gettext</CODE>, 270*946379e7Schristoshas the purpose of creating a MO file out of a PO file, and PO mode uses 271*946379e7Schristosthe features of this program for checking the overall format of a PO file, 272*946379e7Schristosas well as all individual entries. 273*946379e7Schristos 274*946379e7Schristos</P> 275*946379e7Schristos<P> 276*946379e7Schristos<A NAME="IDX334"></A> 277*946379e7SchristosThe program <CODE>msgfmt</CODE> runs asynchronously with Emacs, so the 278*946379e7Schristostranslator regains control immediately while her PO file is being studied. 279*946379e7SchristosError output is collected in the Emacs <SAMP>‘*compilation*’</SAMP> buffer, 280*946379e7Schristosdisplayed in another window. The regular Emacs command <KBD>C-x`</KBD> 281*946379e7Schristos(<CODE>next-error</CODE>), as well as other usual compile commands, allow the 282*946379e7Schristostranslator to reposition quickly to the offending parts of the PO file. 283*946379e7SchristosOnce the cursor is on the line in error, the translator may decide on 284*946379e7Schristosany PO mode action which would help correcting the error. 285*946379e7Schristos 286*946379e7Schristos</P> 287*946379e7Schristos 288*946379e7Schristos 289*946379e7Schristos<H3><A NAME="SEC55" HREF="gettext_toc.html#TOC55">8.3.3 Entry Positioning</A></H3> 290*946379e7Schristos 291*946379e7Schristos<P> 292*946379e7Schristos<A NAME="IDX335"></A> 293*946379e7SchristosThe cursor in a PO file window is almost always part of 294*946379e7Schristosan entry. The only exceptions are the special case when the cursor 295*946379e7Schristosis after the last entry in the file, or when the PO file is 296*946379e7Schristosempty. The entry where the cursor is found to be is said to be the 297*946379e7Schristoscurrent entry. Many PO mode commands operate on the current entry, 298*946379e7Schristosso moving the cursor does more than allowing the translator to browse 299*946379e7Schristosthe PO file, this also selects on which entry commands operate. 300*946379e7Schristos 301*946379e7Schristos</P> 302*946379e7Schristos<P> 303*946379e7Schristos<A NAME="IDX336"></A> 304*946379e7SchristosSome PO mode commands alter the position of the cursor in a specialized 305*946379e7Schristosway. A few of those special purpose positioning are described here, 306*946379e7Schristosthe others are described in following sections (for a complete list try 307*946379e7Schristos<KBD>C-h m</KBD>): 308*946379e7Schristos 309*946379e7Schristos</P> 310*946379e7Schristos<DL COMPACT> 311*946379e7Schristos 312*946379e7Schristos<DT><KBD>.</KBD> 313*946379e7Schristos<DD> 314*946379e7Schristos<A NAME="IDX337"></A> 315*946379e7SchristosRedisplay the current entry (<CODE>po-current-entry</CODE>). 316*946379e7Schristos 317*946379e7Schristos<DT><KBD>n</KBD> 318*946379e7Schristos<DD> 319*946379e7Schristos<A NAME="IDX338"></A> 320*946379e7SchristosSelect the entry after the current one (<CODE>po-next-entry</CODE>). 321*946379e7Schristos 322*946379e7Schristos<DT><KBD>p</KBD> 323*946379e7Schristos<DD> 324*946379e7Schristos<A NAME="IDX339"></A> 325*946379e7SchristosSelect the entry before the current one (<CODE>po-previous-entry</CODE>). 326*946379e7Schristos 327*946379e7Schristos<DT><KBD><</KBD> 328*946379e7Schristos<DD> 329*946379e7Schristos<A NAME="IDX340"></A> 330*946379e7SchristosSelect the first entry in the PO file (<CODE>po-first-entry</CODE>). 331*946379e7Schristos 332*946379e7Schristos<DT><KBD>></KBD> 333*946379e7Schristos<DD> 334*946379e7Schristos<A NAME="IDX341"></A> 335*946379e7SchristosSelect the last entry in the PO file (<CODE>po-last-entry</CODE>). 336*946379e7Schristos 337*946379e7Schristos<DT><KBD>m</KBD> 338*946379e7Schristos<DD> 339*946379e7Schristos<A NAME="IDX342"></A> 340*946379e7SchristosRecord the location of the current entry for later use 341*946379e7Schristos(<CODE>po-push-location</CODE>). 342*946379e7Schristos 343*946379e7Schristos<DT><KBD>r</KBD> 344*946379e7Schristos<DD> 345*946379e7Schristos<A NAME="IDX343"></A> 346*946379e7SchristosReturn to a previously saved entry location (<CODE>po-pop-location</CODE>). 347*946379e7Schristos 348*946379e7Schristos<DT><KBD>x</KBD> 349*946379e7Schristos<DD> 350*946379e7Schristos<A NAME="IDX344"></A> 351*946379e7SchristosExchange the current entry location with the previously saved one 352*946379e7Schristos(<CODE>po-exchange-location</CODE>). 353*946379e7Schristos 354*946379e7Schristos</DL> 355*946379e7Schristos 356*946379e7Schristos<P> 357*946379e7Schristos<A NAME="IDX345"></A> 358*946379e7Schristos<A NAME="IDX346"></A> 359*946379e7SchristosAny Emacs command able to reposition the cursor may be used 360*946379e7Schristosto select the current entry in PO mode, including commands which 361*946379e7Schristosmove by characters, lines, paragraphs, screens or pages, and search 362*946379e7Schristoscommands. However, there is a kind of standard way to display the 363*946379e7Schristoscurrent entry in PO mode, which usual Emacs commands moving 364*946379e7Schristosthe cursor do not especially try to enforce. The command <KBD>.</KBD> 365*946379e7Schristos(<CODE>po-current-entry</CODE>) has the sole purpose of redisplaying the 366*946379e7Schristoscurrent entry properly, after the current entry has been changed by 367*946379e7Schristosmeans external to PO mode, or the Emacs screen otherwise altered. 368*946379e7Schristos 369*946379e7Schristos</P> 370*946379e7Schristos<P> 371*946379e7SchristosIt is yet to be decided if PO mode helps the translator, or otherwise 372*946379e7Schristosirritates her, by forcing a rigid window disposition while she 373*946379e7Schristosis doing her work. We originally had quite precise ideas about 374*946379e7Schristoshow windows should behave, but on the other hand, anyone used to 375*946379e7SchristosEmacs is often happy to keep full control. Maybe a fixed window 376*946379e7Schristosdisposition might be offered as a PO mode option that the translator 377*946379e7Schristosmight activate or deactivate at will, so it could be offered on an 378*946379e7Schristosexperimental basis. If nobody feels a real need for using it, or 379*946379e7Schristosa compulsion for writing it, we should drop this whole idea. 380*946379e7SchristosThe incentive for doing it should come from translators rather than 381*946379e7Schristosprogrammers, as opinions from an experienced translator are surely 382*946379e7Schristosmore worth to me than opinions from programmers <EM>thinking</EM> about 383*946379e7Schristoshow <EM>others</EM> should do translation. 384*946379e7Schristos 385*946379e7Schristos</P> 386*946379e7Schristos<P> 387*946379e7Schristos<A NAME="IDX347"></A> 388*946379e7Schristos<A NAME="IDX348"></A> 389*946379e7Schristos<A NAME="IDX349"></A> 390*946379e7Schristos<A NAME="IDX350"></A> 391*946379e7SchristosThe commands <KBD>n</KBD> (<CODE>po-next-entry</CODE>) and <KBD>p</KBD> 392*946379e7Schristos(<CODE>po-previous-entry</CODE>) move the cursor the entry following, 393*946379e7Schristosor preceding, the current one. If <KBD>n</KBD> is given while the 394*946379e7Schristoscursor is on the last entry of the PO file, or if <KBD>p</KBD> 395*946379e7Schristosis given while the cursor is on the first entry, no move is done. 396*946379e7Schristos 397*946379e7Schristos</P> 398*946379e7Schristos<P> 399*946379e7Schristos<A NAME="IDX351"></A> 400*946379e7Schristos<A NAME="IDX352"></A> 401*946379e7Schristos<A NAME="IDX353"></A> 402*946379e7Schristos<A NAME="IDX354"></A> 403*946379e7SchristosThe commands <KBD><</KBD> (<CODE>po-first-entry</CODE>) and <KBD>></KBD> 404*946379e7Schristos(<CODE>po-last-entry</CODE>) move the cursor to the first entry, or last 405*946379e7Schristosentry, of the PO file. When the cursor is located past the last 406*946379e7Schristosentry in a PO file, most PO mode commands will return an error saying 407*946379e7Schristos<SAMP>‘After last entry’</SAMP>. Moreover, the commands <KBD><</KBD> and <KBD>></KBD> 408*946379e7Schristoshave the special property of being able to work even when the cursor 409*946379e7Schristosis not into some PO file entry, and one may use them for nicely 410*946379e7Schristoscorrecting this situation. But even these commands will fail on a 411*946379e7Schristostruly empty PO file. There are development plans for the PO mode for it 412*946379e7Schristosto interactively fill an empty PO file from sources. See section <A HREF="gettext_4.html#SEC16">4.5 Marking Translatable Strings</A>. 413*946379e7Schristos 414*946379e7Schristos</P> 415*946379e7Schristos<P> 416*946379e7SchristosThe translator may decide, before working at the translation of 417*946379e7Schristosa particular entry, that she needs to browse the remainder of the 418*946379e7SchristosPO file, maybe for finding the terminology or phraseology used 419*946379e7Schristosin related entries. She can of course use the standard Emacs idioms 420*946379e7Schristosfor saving the current cursor location in some register, and use that 421*946379e7Schristosregister for getting back, or else, use the location ring. 422*946379e7Schristos 423*946379e7Schristos</P> 424*946379e7Schristos<P> 425*946379e7Schristos<A NAME="IDX355"></A> 426*946379e7Schristos<A NAME="IDX356"></A> 427*946379e7Schristos<A NAME="IDX357"></A> 428*946379e7Schristos<A NAME="IDX358"></A> 429*946379e7SchristosPO mode offers another approach, by which cursor locations may be saved 430*946379e7Schristosonto a special stack. The command <KBD>m</KBD> (<CODE>po-push-location</CODE>) 431*946379e7Schristosmerely adds the location of current entry to the stack, pushing 432*946379e7Schristosthe already saved locations under the new one. The command 433*946379e7Schristos<KBD>r</KBD> (<CODE>po-pop-location</CODE>) consumes the top stack element and 434*946379e7Schristosrepositions the cursor to the entry associated with that top element. 435*946379e7SchristosThis position is then lost, for the next <KBD>r</KBD> will move the cursor 436*946379e7Schristosto the previously saved location, and so on until no locations remain 437*946379e7Schristoson the stack. 438*946379e7Schristos 439*946379e7Schristos</P> 440*946379e7Schristos<P> 441*946379e7SchristosIf the translator wants the position to be kept on the location stack, 442*946379e7Schristosmaybe for taking a look at the entry associated with the top 443*946379e7Schristoselement, then go elsewhere with the intent of getting back later, she 444*946379e7Schristosought to use <KBD>m</KBD> immediately after <KBD>r</KBD>. 445*946379e7Schristos 446*946379e7Schristos</P> 447*946379e7Schristos<P> 448*946379e7Schristos<A NAME="IDX359"></A> 449*946379e7Schristos<A NAME="IDX360"></A> 450*946379e7SchristosThe command <KBD>x</KBD> (<CODE>po-exchange-location</CODE>) simultaneously 451*946379e7Schristosrepositions the cursor to the entry associated with the top element of 452*946379e7Schristosthe stack of saved locations, and replaces that top element with the 453*946379e7Schristoslocation of the current entry before the move. Consequently, repeating 454*946379e7Schristosthe <KBD>x</KBD> command toggles alternatively between two entries. 455*946379e7SchristosFor achieving this, the translator will position the cursor on the 456*946379e7Schristosfirst entry, use <KBD>m</KBD>, then position to the second entry, and 457*946379e7Schristosmerely use <KBD>x</KBD> for making the switch. 458*946379e7Schristos 459*946379e7Schristos</P> 460*946379e7Schristos 461*946379e7Schristos 462*946379e7Schristos<H3><A NAME="SEC56" HREF="gettext_toc.html#TOC56">8.3.4 Normalizing Strings in Entries</A></H3> 463*946379e7Schristos<P> 464*946379e7Schristos<A NAME="IDX361"></A> 465*946379e7Schristos 466*946379e7Schristos</P> 467*946379e7Schristos<P> 468*946379e7SchristosThere are many different ways for encoding a particular string into a 469*946379e7SchristosPO file entry, because there are so many different ways to split and 470*946379e7Schristosquote multi-line strings, and even, to represent special characters 471*946379e7Schristosby backslashed escaped sequences. Some features of PO mode rely on 472*946379e7Schristosthe ability for PO mode to scan an already existing PO file for a 473*946379e7Schristosparticular string encoded into the <CODE>msgid</CODE> field of some entry. 474*946379e7SchristosEven if PO mode has internally all the built-in machinery for 475*946379e7Schristosimplementing this recognition easily, doing it fast is technically 476*946379e7Schristosdifficult. To facilitate a solution to this efficiency problem, 477*946379e7Schristoswe decided on a canonical representation for strings. 478*946379e7Schristos 479*946379e7Schristos</P> 480*946379e7Schristos<P> 481*946379e7SchristosA conventional representation of strings in a PO file is currently 482*946379e7Schristosunder discussion, and PO mode experiments with a canonical representation. 483*946379e7SchristosHaving both <CODE>xgettext</CODE> and PO mode converging towards a uniform 484*946379e7Schristosway of representing equivalent strings would be useful, as the internal 485*946379e7Schristosnormalization needed by PO mode could be automatically satisfied 486*946379e7Schristoswhen using <CODE>xgettext</CODE> from GNU <CODE>gettext</CODE>. An explicit 487*946379e7SchristosPO mode normalization should then be only necessary for PO files 488*946379e7Schristosimported from elsewhere, or for when the convention itself evolves. 489*946379e7Schristos 490*946379e7Schristos</P> 491*946379e7Schristos<P> 492*946379e7SchristosSo, for achieving normalization of at least the strings of a given 493*946379e7SchristosPO file needing a canonical representation, the following PO mode 494*946379e7Schristoscommand is available: 495*946379e7Schristos 496*946379e7Schristos</P> 497*946379e7Schristos<P> 498*946379e7Schristos<A NAME="IDX362"></A> 499*946379e7Schristos<DL COMPACT> 500*946379e7Schristos 501*946379e7Schristos<DT><KBD>M-x po-normalize</KBD> 502*946379e7Schristos<DD> 503*946379e7Schristos<A NAME="IDX363"></A> 504*946379e7SchristosTidy the whole PO file by making entries more uniform. 505*946379e7Schristos 506*946379e7Schristos</DL> 507*946379e7Schristos 508*946379e7Schristos<P> 509*946379e7SchristosThe special command <KBD>M-x po-normalize</KBD>, which has no associated 510*946379e7Schristoskeys, revises all entries, ensuring that strings of both original 511*946379e7Schristosand translated entries use uniform internal quoting in the PO file. 512*946379e7SchristosIt also removes any crumb after the last entry. This command may be 513*946379e7Schristosuseful for PO files freshly imported from elsewhere, or if we ever 514*946379e7Schristosimprove on the canonical quoting format we use. This canonical format 515*946379e7Schristosis not only meant for getting cleaner PO files, but also for greatly 516*946379e7Schristosspeeding up <CODE>msgid</CODE> string lookup for some other PO mode commands. 517*946379e7Schristos 518*946379e7Schristos</P> 519*946379e7Schristos<P> 520*946379e7Schristos<KBD>M-x po-normalize</KBD> presently makes three passes over the entries. 521*946379e7SchristosThe first implements heuristics for converting PO files for GNU 522*946379e7Schristos<CODE>gettext</CODE> 0.6 and earlier, in which <CODE>msgid</CODE> and <CODE>msgstr</CODE> 523*946379e7Schristosfields were using K&R style C string syntax for multi-line strings. 524*946379e7SchristosThese heuristics may fail for comments not related to obsolete 525*946379e7Schristosentries and ending with a backslash; they also depend on subsequent 526*946379e7Schristospasses for finalizing the proper commenting of continued lines for 527*946379e7Schristosobsolete entries. This first pass might disappear once all oldish PO 528*946379e7Schristosfiles would have been adjusted. The second and third pass normalize 529*946379e7Schristosall <CODE>msgid</CODE> and <CODE>msgstr</CODE> strings respectively. They also 530*946379e7Schristosclean out those trailing backslashes used by XView's <CODE>msgfmt</CODE> 531*946379e7Schristosfor continued lines. 532*946379e7Schristos 533*946379e7Schristos</P> 534*946379e7Schristos<P> 535*946379e7Schristos<A NAME="IDX364"></A> 536*946379e7SchristosHaving such an explicit normalizing command allows for importing PO 537*946379e7Schristosfiles from other sources, but also eases the evolution of the current 538*946379e7Schristosconvention, evolution driven mostly by aesthetic concerns, as of now. 539*946379e7SchristosIt is easy to make suggested adjustments at a later time, as the 540*946379e7Schristosnormalizing command and eventually, other GNU <CODE>gettext</CODE> tools 541*946379e7Schristosshould greatly automate conformance. A description of the canonical 542*946379e7Schristosstring format is given below, for the particular benefit of those not 543*946379e7Schristoshaving Emacs handy, and who would nevertheless want to handcraft 544*946379e7Schristostheir PO files in nice ways. 545*946379e7Schristos 546*946379e7Schristos</P> 547*946379e7Schristos<P> 548*946379e7Schristos<A NAME="IDX365"></A> 549*946379e7SchristosRight now, in PO mode, strings are single line or multi-line. A string 550*946379e7Schristosgoes multi-line if and only if it has <EM>embedded</EM> newlines, that 551*946379e7Schristosis, if it matches <SAMP>‘[^\n]\n+[^\n]’</SAMP>. So, we would have: 552*946379e7Schristos 553*946379e7Schristos</P> 554*946379e7Schristos 555*946379e7Schristos<PRE> 556*946379e7Schristosmsgstr "\n\nHello, world!\n\n\n" 557*946379e7Schristos</PRE> 558*946379e7Schristos 559*946379e7Schristos<P> 560*946379e7Schristosbut, replacing the space by a newline, this becomes: 561*946379e7Schristos 562*946379e7Schristos</P> 563*946379e7Schristos 564*946379e7Schristos<PRE> 565*946379e7Schristosmsgstr "" 566*946379e7Schristos"\n" 567*946379e7Schristos"\n" 568*946379e7Schristos"Hello,\n" 569*946379e7Schristos"world!\n" 570*946379e7Schristos"\n" 571*946379e7Schristos"\n" 572*946379e7Schristos</PRE> 573*946379e7Schristos 574*946379e7Schristos<P> 575*946379e7SchristosWe are deliberately using a caricatural example, here, to make the 576*946379e7Schristospoint clearer. Usually, multi-lines are not that bad looking. 577*946379e7SchristosIt is probable that we will implement the following suggestion. 578*946379e7SchristosWe might lump together all initial newlines into the empty string, 579*946379e7Schristosand also all newlines introducing empty lines (that is, for <VAR>n</VAR> 580*946379e7Schristos> 1, the <VAR>n</VAR>-1'th last newlines would go together on a separate 581*946379e7Schristosstring), so making the previous example appear: 582*946379e7Schristos 583*946379e7Schristos</P> 584*946379e7Schristos 585*946379e7Schristos<PRE> 586*946379e7Schristosmsgstr "\n\n" 587*946379e7Schristos"Hello,\n" 588*946379e7Schristos"world!\n" 589*946379e7Schristos"\n\n" 590*946379e7Schristos</PRE> 591*946379e7Schristos 592*946379e7Schristos<P> 593*946379e7SchristosThere are a few yet undecided little points about string normalization, 594*946379e7Schristosto be documented in this manual, once these questions settle. 595*946379e7Schristos 596*946379e7Schristos</P> 597*946379e7Schristos 598*946379e7Schristos 599*946379e7Schristos<H3><A NAME="SEC57" HREF="gettext_toc.html#TOC57">8.3.5 Translated Entries</A></H3> 600*946379e7Schristos<P> 601*946379e7Schristos<A NAME="IDX366"></A> 602*946379e7Schristos 603*946379e7Schristos</P> 604*946379e7Schristos<P> 605*946379e7SchristosEach PO file entry for which the <CODE>msgstr</CODE> field has been filled with 606*946379e7Schristosa translation, and which is not marked as fuzzy (see section <A HREF="gettext_8.html#SEC58">8.3.6 Fuzzy Entries</A>), 607*946379e7Schristosis said to be a <EM>translated</EM> entry. Only translated entries will 608*946379e7Schristoslater be compiled by GNU <CODE>msgfmt</CODE> and become usable in programs. 609*946379e7SchristosOther entry types will be excluded; translation will not occur for them. 610*946379e7Schristos 611*946379e7Schristos</P> 612*946379e7Schristos<P> 613*946379e7Schristos<A NAME="IDX367"></A> 614*946379e7SchristosSome commands are more specifically related to translated entry processing. 615*946379e7Schristos 616*946379e7Schristos</P> 617*946379e7Schristos<DL COMPACT> 618*946379e7Schristos 619*946379e7Schristos<DT><KBD>t</KBD> 620*946379e7Schristos<DD> 621*946379e7Schristos<A NAME="IDX368"></A> 622*946379e7SchristosFind the next translated entry (<CODE>po-next-translated-entry</CODE>). 623*946379e7Schristos 624*946379e7Schristos<DT><KBD>T</KBD> 625*946379e7Schristos<DD> 626*946379e7Schristos<A NAME="IDX369"></A> 627*946379e7SchristosFind the previous translated entry (<CODE>po-previous-translated-entry</CODE>). 628*946379e7Schristos 629*946379e7Schristos</DL> 630*946379e7Schristos 631*946379e7Schristos<P> 632*946379e7Schristos<A NAME="IDX370"></A> 633*946379e7Schristos<A NAME="IDX371"></A> 634*946379e7Schristos<A NAME="IDX372"></A> 635*946379e7Schristos<A NAME="IDX373"></A> 636*946379e7SchristosThe commands <KBD>t</KBD> (<CODE>po-next-translated-entry</CODE>) and <KBD>T</KBD> 637*946379e7Schristos(<CODE>po-previous-translated-entry</CODE>) move forwards or backwards, chasing 638*946379e7Schristosfor an translated entry. If none is found, the search is extended and 639*946379e7Schristoswraps around in the PO file buffer. 640*946379e7Schristos 641*946379e7Schristos</P> 642*946379e7Schristos<P> 643*946379e7Schristos<A NAME="IDX374"></A> 644*946379e7SchristosTranslated entries usually result from the translator having edited in 645*946379e7Schristosa translation for them, section <A HREF="gettext_8.html#SEC61">8.3.9 Modifying Translations</A>. However, if the 646*946379e7Schristosvariable <CODE>po-auto-fuzzy-on-edit</CODE> is not <CODE>nil</CODE>, the entry having 647*946379e7Schristosreceived a new translation first becomes a fuzzy entry, which ought to 648*946379e7Schristosbe later unfuzzied before becoming an official, genuine translated entry. 649*946379e7SchristosSee section <A HREF="gettext_8.html#SEC58">8.3.6 Fuzzy Entries</A>. 650*946379e7Schristos 651*946379e7Schristos</P> 652*946379e7Schristos 653*946379e7Schristos 654*946379e7Schristos<H3><A NAME="SEC58" HREF="gettext_toc.html#TOC58">8.3.6 Fuzzy Entries</A></H3> 655*946379e7Schristos<P> 656*946379e7Schristos<A NAME="IDX375"></A> 657*946379e7Schristos 658*946379e7Schristos</P> 659*946379e7Schristos<P> 660*946379e7Schristos<A NAME="IDX376"></A> 661*946379e7Schristos<A NAME="IDX377"></A> 662*946379e7SchristosEach PO file entry may have a set of <EM>attributes</EM>, which are 663*946379e7Schristosqualities given a name and explicitly associated with the translation, 664*946379e7Schristosusing a special system comment. One of these attributes 665*946379e7Schristoshas the name <CODE>fuzzy</CODE>, and entries having this attribute are said 666*946379e7Schristosto have a fuzzy translation. They are called fuzzy entries, for short. 667*946379e7Schristos 668*946379e7Schristos</P> 669*946379e7Schristos<P> 670*946379e7SchristosFuzzy entries, even if they account for translated entries for 671*946379e7Schristosmost other purposes, usually call for revision by the translator. 672*946379e7SchristosThose may be produced by applying the program <CODE>msgmerge</CODE> to 673*946379e7Schristosupdate an older translated PO files according to a new PO template 674*946379e7Schristosfile, when this tool hypothesises that some new <CODE>msgid</CODE> has 675*946379e7Schristosbeen modified only slightly out of an older one, and chooses to pair 676*946379e7Schristoswhat it thinks to be the old translation for the new modified entry. 677*946379e7SchristosThe slight alteration in the original string (the <CODE>msgid</CODE> string) 678*946379e7Schristosshould often be reflected in the translated string, and this requires 679*946379e7Schristosthe intervention of the translator. For this reason, <CODE>msgmerge</CODE> 680*946379e7Schristosmight mark some entries as being fuzzy. 681*946379e7Schristos 682*946379e7Schristos</P> 683*946379e7Schristos<P> 684*946379e7Schristos<A NAME="IDX378"></A> 685*946379e7SchristosAlso, the translator may decide herself to mark an entry as fuzzy 686*946379e7Schristosfor her own convenience, when she wants to remember that the entry 687*946379e7Schristoshas to be later revisited. So, some commands are more specifically 688*946379e7Schristosrelated to fuzzy entry processing. 689*946379e7Schristos 690*946379e7Schristos</P> 691*946379e7Schristos<DL COMPACT> 692*946379e7Schristos 693*946379e7Schristos<DT><KBD>z</KBD> 694*946379e7Schristos<DD> 695*946379e7Schristos<A NAME="IDX379"></A> 696*946379e7SchristosFind the next fuzzy entry (<CODE>po-next-fuzzy-entry</CODE>). 697*946379e7Schristos 698*946379e7Schristos<DT><KBD>Z</KBD> 699*946379e7Schristos<DD> 700*946379e7Schristos<A NAME="IDX380"></A> 701*946379e7SchristosFind the previous fuzzy entry (<CODE>po-previous-fuzzy-entry</CODE>). 702*946379e7Schristos 703*946379e7Schristos<DT><KBD><KBD>TAB</KBD></KBD> 704*946379e7Schristos<DD> 705*946379e7Schristos<A NAME="IDX381"></A> 706*946379e7SchristosRemove the fuzzy attribute of the current entry (<CODE>po-unfuzzy</CODE>). 707*946379e7Schristos 708*946379e7Schristos</DL> 709*946379e7Schristos 710*946379e7Schristos<P> 711*946379e7Schristos<A NAME="IDX382"></A> 712*946379e7Schristos<A NAME="IDX383"></A> 713*946379e7Schristos<A NAME="IDX384"></A> 714*946379e7Schristos<A NAME="IDX385"></A> 715*946379e7SchristosThe commands <KBD>z</KBD> (<CODE>po-next-fuzzy-entry</CODE>) and <KBD>Z</KBD> 716*946379e7Schristos(<CODE>po-previous-fuzzy-entry</CODE>) move forwards or backwards, chasing for 717*946379e7Schristosa fuzzy entry. If none is found, the search is extended and wraps 718*946379e7Schristosaround in the PO file buffer. 719*946379e7Schristos 720*946379e7Schristos</P> 721*946379e7Schristos<P> 722*946379e7Schristos<A NAME="IDX386"></A> 723*946379e7Schristos<A NAME="IDX387"></A> 724*946379e7Schristos<A NAME="IDX388"></A> 725*946379e7SchristosThe command <KBD><KBD>TAB</KBD></KBD> (<CODE>po-unfuzzy</CODE>) removes the fuzzy 726*946379e7Schristosattribute associated with an entry, usually leaving it translated. 727*946379e7SchristosFurther, if the variable <CODE>po-auto-select-on-unfuzzy</CODE> has not 728*946379e7Schristosthe <CODE>nil</CODE> value, the <KBD><KBD>TAB</KBD></KBD> command will automatically chase 729*946379e7Schristosfor another interesting entry to work on. The initial value of 730*946379e7Schristos<CODE>po-auto-select-on-unfuzzy</CODE> is <CODE>nil</CODE>. 731*946379e7Schristos 732*946379e7Schristos</P> 733*946379e7Schristos<P> 734*946379e7SchristosThe initial value of <CODE>po-auto-fuzzy-on-edit</CODE> is <CODE>nil</CODE>. However, 735*946379e7Schristosif the variable <CODE>po-auto-fuzzy-on-edit</CODE> is set to <CODE>t</CODE>, any entry 736*946379e7Schristosedited through the <KBD><KBD>RET</KBD></KBD> command is marked fuzzy, as a way to 737*946379e7Schristosensure some kind of double check, later. In this case, the usual paradigm 738*946379e7Schristosis that an entry becomes fuzzy (if not already) whenever the translator 739*946379e7Schristosmodifies it. If she is satisfied with the translation, she then uses 740*946379e7Schristos<KBD><KBD>TAB</KBD></KBD> to pick another entry to work on, clearing the fuzzy attribute 741*946379e7Schristoson the same blow. If she is not satisfied yet, she merely uses <KBD><KBD>SPC</KBD></KBD> 742*946379e7Schristosto chase another entry, leaving the entry fuzzy. 743*946379e7Schristos 744*946379e7Schristos</P> 745*946379e7Schristos<P> 746*946379e7Schristos<A NAME="IDX389"></A> 747*946379e7Schristos<A NAME="IDX390"></A> 748*946379e7SchristosThe translator may also use the <KBD><KBD>DEL</KBD></KBD> command 749*946379e7Schristos(<CODE>po-fade-out-entry</CODE>) over any translated entry to mark it as being 750*946379e7Schristosfuzzy, when she wants to easily leave a trace she wants to later return 751*946379e7Schristosworking at this entry. 752*946379e7Schristos 753*946379e7Schristos</P> 754*946379e7Schristos<P> 755*946379e7SchristosAlso, when time comes to quit working on a PO file buffer with the <KBD>q</KBD> 756*946379e7Schristoscommand, the translator is asked for confirmation, if fuzzy string 757*946379e7Schristosstill exists. 758*946379e7Schristos 759*946379e7Schristos</P> 760*946379e7Schristos 761*946379e7Schristos 762*946379e7Schristos<H3><A NAME="SEC59" HREF="gettext_toc.html#TOC59">8.3.7 Untranslated Entries</A></H3> 763*946379e7Schristos<P> 764*946379e7Schristos<A NAME="IDX391"></A> 765*946379e7Schristos 766*946379e7Schristos</P> 767*946379e7Schristos<P> 768*946379e7SchristosWhen <CODE>xgettext</CODE> originally creates a PO file, unless told 769*946379e7Schristosotherwise, it initializes the <CODE>msgid</CODE> field with the untranslated 770*946379e7Schristosstring, and leaves the <CODE>msgstr</CODE> string to be empty. Such entries, 771*946379e7Schristoshaving an empty translation, are said to be <EM>untranslated</EM> entries. 772*946379e7SchristosLater, when the programmer slightly modifies some string right in 773*946379e7Schristosthe program, this change is later reflected in the PO file 774*946379e7Schristosby the appearance of a new untranslated entry for the modified string. 775*946379e7Schristos 776*946379e7Schristos</P> 777*946379e7Schristos<P> 778*946379e7SchristosThe usual commands moving from entry to entry consider untranslated 779*946379e7Schristosentries on the same level as active entries. Untranslated entries 780*946379e7Schristosare easily recognizable by the fact they end with <SAMP>‘msgstr ""’</SAMP>. 781*946379e7Schristos 782*946379e7Schristos</P> 783*946379e7Schristos<P> 784*946379e7Schristos<A NAME="IDX392"></A> 785*946379e7SchristosThe work of the translator might be (quite naively) seen as the process 786*946379e7Schristosof seeking for an untranslated entry, editing a translation for 787*946379e7Schristosit, and repeating these actions until no untranslated entries remain. 788*946379e7SchristosSome commands are more specifically related to untranslated entry 789*946379e7Schristosprocessing. 790*946379e7Schristos 791*946379e7Schristos</P> 792*946379e7Schristos<DL COMPACT> 793*946379e7Schristos 794*946379e7Schristos<DT><KBD>u</KBD> 795*946379e7Schristos<DD> 796*946379e7Schristos<A NAME="IDX393"></A> 797*946379e7SchristosFind the next untranslated entry (<CODE>po-next-untranslated-entry</CODE>). 798*946379e7Schristos 799*946379e7Schristos<DT><KBD>U</KBD> 800*946379e7Schristos<DD> 801*946379e7Schristos<A NAME="IDX394"></A> 802*946379e7SchristosFind the previous untranslated entry (<CODE>po-previous-untransted-entry</CODE>). 803*946379e7Schristos 804*946379e7Schristos<DT><KBD>k</KBD> 805*946379e7Schristos<DD> 806*946379e7Schristos<A NAME="IDX395"></A> 807*946379e7SchristosTurn the current entry into an untranslated one (<CODE>po-kill-msgstr</CODE>). 808*946379e7Schristos 809*946379e7Schristos</DL> 810*946379e7Schristos 811*946379e7Schristos<P> 812*946379e7Schristos<A NAME="IDX396"></A> 813*946379e7Schristos<A NAME="IDX397"></A> 814*946379e7Schristos<A NAME="IDX398"></A> 815*946379e7Schristos<A NAME="IDX399"></A> 816*946379e7SchristosThe commands <KBD>u</KBD> (<CODE>po-next-untranslated-entry</CODE>) and <KBD>U</KBD> 817*946379e7Schristos(<CODE>po-previous-untransted-entry</CODE>) move forwards or backwards, 818*946379e7Schristoschasing for an untranslated entry. If none is found, the search is 819*946379e7Schristosextended and wraps around in the PO file buffer. 820*946379e7Schristos 821*946379e7Schristos</P> 822*946379e7Schristos<P> 823*946379e7Schristos<A NAME="IDX400"></A> 824*946379e7Schristos<A NAME="IDX401"></A> 825*946379e7SchristosAn entry can be turned back into an untranslated entry by 826*946379e7Schristosmerely emptying its translation, using the command <KBD>k</KBD> 827*946379e7Schristos(<CODE>po-kill-msgstr</CODE>). See section <A HREF="gettext_8.html#SEC61">8.3.9 Modifying Translations</A>. 828*946379e7Schristos 829*946379e7Schristos</P> 830*946379e7Schristos<P> 831*946379e7SchristosAlso, when time comes to quit working on a PO file buffer 832*946379e7Schristoswith the <KBD>q</KBD> command, the translator is asked for confirmation, 833*946379e7Schristosif some untranslated string still exists. 834*946379e7Schristos 835*946379e7Schristos</P> 836*946379e7Schristos 837*946379e7Schristos 838*946379e7Schristos<H3><A NAME="SEC60" HREF="gettext_toc.html#TOC60">8.3.8 Obsolete Entries</A></H3> 839*946379e7Schristos<P> 840*946379e7Schristos<A NAME="IDX402"></A> 841*946379e7Schristos 842*946379e7Schristos</P> 843*946379e7Schristos<P> 844*946379e7SchristosBy <EM>obsolete</EM> PO file entries, we mean those entries which are 845*946379e7Schristoscommented out, usually by <CODE>msgmerge</CODE> when it found that the 846*946379e7Schristostranslation is not needed anymore by the package being localized. 847*946379e7Schristos 848*946379e7Schristos</P> 849*946379e7Schristos<P> 850*946379e7SchristosThe usual commands moving from entry to entry consider obsolete 851*946379e7Schristosentries on the same level as active entries. Obsolete entries are 852*946379e7Schristoseasily recognizable by the fact that all their lines start with 853*946379e7Schristos<CODE>#</CODE>, even those lines containing <CODE>msgid</CODE> or <CODE>msgstr</CODE>. 854*946379e7Schristos 855*946379e7Schristos</P> 856*946379e7Schristos<P> 857*946379e7SchristosCommands exist for emptying the translation or reinitializing it 858*946379e7Schristosto the original untranslated string. Commands interfacing with the 859*946379e7Schristoskill ring may force some previously saved text into the translation. 860*946379e7SchristosThe user may interactively edit the translation. All these commands 861*946379e7Schristosmay apply to obsolete entries, carefully leaving the entry obsolete 862*946379e7Schristosafter the fact. 863*946379e7Schristos 864*946379e7Schristos</P> 865*946379e7Schristos<P> 866*946379e7Schristos<A NAME="IDX403"></A> 867*946379e7SchristosMoreover, some commands are more specifically related to obsolete 868*946379e7Schristosentry processing. 869*946379e7Schristos 870*946379e7Schristos</P> 871*946379e7Schristos<DL COMPACT> 872*946379e7Schristos 873*946379e7Schristos<DT><KBD>o</KBD> 874*946379e7Schristos<DD> 875*946379e7Schristos<A NAME="IDX404"></A> 876*946379e7SchristosFind the next obsolete entry (<CODE>po-next-obsolete-entry</CODE>). 877*946379e7Schristos 878*946379e7Schristos<DT><KBD>O</KBD> 879*946379e7Schristos<DD> 880*946379e7Schristos<A NAME="IDX405"></A> 881*946379e7SchristosFind the previous obsolete entry (<CODE>po-previous-obsolete-entry</CODE>). 882*946379e7Schristos 883*946379e7Schristos<DT><KBD><KBD>DEL</KBD></KBD> 884*946379e7Schristos<DD> 885*946379e7Schristos<A NAME="IDX406"></A> 886*946379e7SchristosMake an active entry obsolete, or zap out an obsolete entry 887*946379e7Schristos(<CODE>po-fade-out-entry</CODE>). 888*946379e7Schristos 889*946379e7Schristos</DL> 890*946379e7Schristos 891*946379e7Schristos<P> 892*946379e7Schristos<A NAME="IDX407"></A> 893*946379e7Schristos<A NAME="IDX408"></A> 894*946379e7Schristos<A NAME="IDX409"></A> 895*946379e7Schristos<A NAME="IDX410"></A> 896*946379e7SchristosThe commands <KBD>o</KBD> (<CODE>po-next-obsolete-entry</CODE>) and <KBD>O</KBD> 897*946379e7Schristos(<CODE>po-previous-obsolete-entry</CODE>) move forwards or backwards, 898*946379e7Schristoschasing for an obsolete entry. If none is found, the search is 899*946379e7Schristosextended and wraps around in the PO file buffer. 900*946379e7Schristos 901*946379e7Schristos</P> 902*946379e7Schristos<P> 903*946379e7SchristosPO mode does not provide ways for un-commenting an obsolete entry 904*946379e7Schristosand making it active, because this would reintroduce an original 905*946379e7Schristosuntranslated string which does not correspond to any marked string 906*946379e7Schristosin the program sources. This goes with the philosophy of never 907*946379e7Schristosintroducing useless <CODE>msgid</CODE> values. 908*946379e7Schristos 909*946379e7Schristos</P> 910*946379e7Schristos<P> 911*946379e7Schristos<A NAME="IDX411"></A> 912*946379e7Schristos<A NAME="IDX412"></A> 913*946379e7Schristos<A NAME="IDX413"></A> 914*946379e7Schristos<A NAME="IDX414"></A> 915*946379e7SchristosHowever, it is possible to comment out an active entry, so making 916*946379e7Schristosit obsolete. GNU <CODE>gettext</CODE> utilities will later react to the 917*946379e7Schristosdisappearance of a translation by using the untranslated string. 918*946379e7SchristosThe command <KBD><KBD>DEL</KBD></KBD> (<CODE>po-fade-out-entry</CODE>) pushes the current entry 919*946379e7Schristosa little further towards annihilation. If the entry is active (it is a 920*946379e7Schristostranslated entry), then it is first made fuzzy. If it is already fuzzy, 921*946379e7Schristosthen the entry is merely commented out, with confirmation. If the entry 922*946379e7Schristosis already obsolete, then it is completely deleted from the PO file. 923*946379e7SchristosIt is easy to recycle the translation so deleted into some other PO file 924*946379e7Schristosentry, usually one which is untranslated. See section <A HREF="gettext_8.html#SEC61">8.3.9 Modifying Translations</A>. 925*946379e7Schristos 926*946379e7Schristos</P> 927*946379e7Schristos<P> 928*946379e7SchristosHere is a quite interesting problem to solve for later development of 929*946379e7SchristosPO mode, for those nights you are not sleepy. The idea would be that 930*946379e7SchristosPO mode might become bright enough, one of these days, to make good 931*946379e7Schristosguesses at retrieving the most probable candidate, among all obsolete 932*946379e7Schristosentries, for initializing the translation of a newly appeared string. 933*946379e7SchristosI think it might be a quite hard problem to do this algorithmically, as 934*946379e7Schristoswe have to develop good and efficient measures of string similarity. 935*946379e7SchristosRight now, PO mode completely lets the decision to the translator, 936*946379e7Schristoswhen the time comes to find the adequate obsolete translation, it 937*946379e7Schristosmerely tries to provide handy tools for helping her to do so. 938*946379e7Schristos 939*946379e7Schristos</P> 940*946379e7Schristos 941*946379e7Schristos 942*946379e7Schristos<H3><A NAME="SEC61" HREF="gettext_toc.html#TOC61">8.3.9 Modifying Translations</A></H3> 943*946379e7Schristos<P> 944*946379e7Schristos<A NAME="IDX415"></A> 945*946379e7Schristos<A NAME="IDX416"></A> 946*946379e7Schristos 947*946379e7Schristos</P> 948*946379e7Schristos<P> 949*946379e7SchristosPO mode prevents direct modification of the PO file, by the usual 950*946379e7Schristosmeans Emacs gives for altering a buffer's contents. By doing so, 951*946379e7Schristosit pretends helping the translator to avoid little clerical errors 952*946379e7Schristosabout the overall file format, or the proper quoting of strings, 953*946379e7Schristosas those errors would be easily made. Other kinds of errors are 954*946379e7Schristosstill possible, but some may be caught and diagnosed by the batch 955*946379e7Schristosvalidation process, which the translator may always trigger by the 956*946379e7Schristos<KBD>V</KBD> command. For all other errors, the translator has to rely on 957*946379e7Schristosher own judgment, and also on the linguistic reports submitted to her 958*946379e7Schristosby the users of the translated package, having the same mother tongue. 959*946379e7Schristos 960*946379e7Schristos</P> 961*946379e7Schristos<P> 962*946379e7SchristosWhen the time comes to create a translation, correct an error diagnosed 963*946379e7Schristosmechanically or reported by a user, the translators have to resort to 964*946379e7Schristosusing the following commands for modifying the translations. 965*946379e7Schristos 966*946379e7Schristos</P> 967*946379e7Schristos<DL COMPACT> 968*946379e7Schristos 969*946379e7Schristos<DT><KBD><KBD>RET</KBD></KBD> 970*946379e7Schristos<DD> 971*946379e7Schristos<A NAME="IDX417"></A> 972*946379e7SchristosInteractively edit the translation (<CODE>po-edit-msgstr</CODE>). 973*946379e7Schristos 974*946379e7Schristos<DT><KBD><KBD>LFD</KBD></KBD> 975*946379e7Schristos<DD> 976*946379e7Schristos<DT><KBD>C-j</KBD> 977*946379e7Schristos<DD> 978*946379e7Schristos<A NAME="IDX418"></A> 979*946379e7Schristos<A NAME="IDX419"></A> 980*946379e7SchristosReinitialize the translation with the original, untranslated string 981*946379e7Schristos(<CODE>po-msgid-to-msgstr</CODE>). 982*946379e7Schristos 983*946379e7Schristos<DT><KBD>k</KBD> 984*946379e7Schristos<DD> 985*946379e7Schristos<A NAME="IDX420"></A> 986*946379e7SchristosSave the translation on the kill ring, and delete it (<CODE>po-kill-msgstr</CODE>). 987*946379e7Schristos 988*946379e7Schristos<DT><KBD>w</KBD> 989*946379e7Schristos<DD> 990*946379e7Schristos<A NAME="IDX421"></A> 991*946379e7SchristosSave the translation on the kill ring, without deleting it 992*946379e7Schristos(<CODE>po-kill-ring-save-msgstr</CODE>). 993*946379e7Schristos 994*946379e7Schristos<DT><KBD>y</KBD> 995*946379e7Schristos<DD> 996*946379e7Schristos<A NAME="IDX422"></A> 997*946379e7SchristosReplace the translation, taking the new from the kill ring 998*946379e7Schristos(<CODE>po-yank-msgstr</CODE>). 999*946379e7Schristos 1000*946379e7Schristos</DL> 1001*946379e7Schristos 1002*946379e7Schristos<P> 1003*946379e7Schristos<A NAME="IDX423"></A> 1004*946379e7Schristos<A NAME="IDX424"></A> 1005*946379e7SchristosThe command <KBD><KBD>RET</KBD></KBD> (<CODE>po-edit-msgstr</CODE>) opens a new Emacs 1006*946379e7Schristoswindow meant to edit in a new translation, or to modify an already existing 1007*946379e7Schristostranslation. The new window contains a copy of the translation taken from 1008*946379e7Schristosthe current PO file entry, all ready for edition, expunged of all quoting 1009*946379e7Schristosmarks, fully modifiable and with the complete extent of Emacs modifying 1010*946379e7Schristoscommands. When the translator is done with her modifications, she may use 1011*946379e7Schristos<KBD>C-c C-c</KBD> to close the subedit window with the automatically requoted 1012*946379e7Schristosresults, or <KBD>C-c C-k</KBD> to abort her modifications. See section <A HREF="gettext_8.html#SEC63">8.3.11 Details of Sub Edition</A>, 1013*946379e7Schristosfor more information. 1014*946379e7Schristos 1015*946379e7Schristos</P> 1016*946379e7Schristos<P> 1017*946379e7Schristos<A NAME="IDX425"></A> 1018*946379e7Schristos<A NAME="IDX426"></A> 1019*946379e7Schristos<A NAME="IDX427"></A> 1020*946379e7SchristosThe command <KBD><KBD>LFD</KBD></KBD> (<CODE>po-msgid-to-msgstr</CODE>) initializes, or 1021*946379e7Schristosreinitializes the translation with the original string. This command is 1022*946379e7Schristosnormally used when the translator wants to redo a fresh translation of 1023*946379e7Schristosthe original string, disregarding any previous work. 1024*946379e7Schristos 1025*946379e7Schristos</P> 1026*946379e7Schristos<P> 1027*946379e7Schristos<A NAME="IDX428"></A> 1028*946379e7SchristosIt is possible to arrange so, whenever editing an untranslated 1029*946379e7Schristosentry, the <KBD><KBD>LFD</KBD></KBD> command be automatically executed. If you set 1030*946379e7Schristos<CODE>po-auto-edit-with-msgid</CODE> to <CODE>t</CODE>, the translation gets 1031*946379e7Schristosinitialised with the original string, in case none exists already. 1032*946379e7SchristosThe default value for <CODE>po-auto-edit-with-msgid</CODE> is <CODE>nil</CODE>. 1033*946379e7Schristos 1034*946379e7Schristos</P> 1035*946379e7Schristos<P> 1036*946379e7Schristos<A NAME="IDX429"></A> 1037*946379e7SchristosIn fact, whether it is best to start a translation with an empty 1038*946379e7Schristosstring, or rather with a copy of the original string, is a matter of 1039*946379e7Schristostaste or habit. Sometimes, the source language and the 1040*946379e7Schristostarget language are so different that is simply best to start writing 1041*946379e7Schristoson an empty page. At other times, the source and target languages 1042*946379e7Schristosare so close that it would be a waste to retype a number of words 1043*946379e7Schristosalready being written in the original string. A translator may also 1044*946379e7Schristoslike having the original string right under her eyes, as she will 1045*946379e7Schristosprogressively overwrite the original text with the translation, even 1046*946379e7Schristosif this requires some extra editing work to get rid of the original. 1047*946379e7Schristos 1048*946379e7Schristos</P> 1049*946379e7Schristos<P> 1050*946379e7Schristos<A NAME="IDX430"></A> 1051*946379e7Schristos<A NAME="IDX431"></A> 1052*946379e7Schristos<A NAME="IDX432"></A> 1053*946379e7Schristos<A NAME="IDX433"></A> 1054*946379e7Schristos<A NAME="IDX434"></A> 1055*946379e7SchristosThe command <KBD>k</KBD> (<CODE>po-kill-msgstr</CODE>) merely empties the 1056*946379e7Schristostranslation string, so turning the entry into an untranslated 1057*946379e7Schristosone. But while doing so, its previous contents is put apart in 1058*946379e7Schristosa special place, known as the kill ring. The command <KBD>w</KBD> 1059*946379e7Schristos(<CODE>po-kill-ring-save-msgstr</CODE>) has also the effect of taking a 1060*946379e7Schristoscopy of the translation onto the kill ring, but it otherwise leaves 1061*946379e7Schristosthe entry alone, and does <EM>not</EM> remove the translation from the 1062*946379e7Schristosentry. Both commands use exactly the Emacs kill ring, which is shared 1063*946379e7Schristosbetween buffers, and which is well known already to Emacs lovers. 1064*946379e7Schristos 1065*946379e7Schristos</P> 1066*946379e7Schristos<P> 1067*946379e7SchristosThe translator may use <KBD>k</KBD> or <KBD>w</KBD> many times in the course 1068*946379e7Schristosof her work, as the kill ring may hold several saved translations. 1069*946379e7SchristosFrom the kill ring, strings may later be reinserted in various 1070*946379e7SchristosEmacs buffers. In particular, the kill ring may be used for moving 1071*946379e7Schristostranslation strings between different entries of a single PO file 1072*946379e7Schristosbuffer, or if the translator is handling many such buffers at once, 1073*946379e7Schristoseven between PO files. 1074*946379e7Schristos 1075*946379e7Schristos</P> 1076*946379e7Schristos<P> 1077*946379e7SchristosTo facilitate exchanges with buffers which are not in PO mode, the 1078*946379e7Schristostranslation string put on the kill ring by the <KBD>k</KBD> command is fully 1079*946379e7Schristosunquoted before being saved: external quotes are removed, multi-line 1080*946379e7Schristosstrings are concatenated, and backslash escaped sequences are turned 1081*946379e7Schristosinto their corresponding characters. In the special case of obsolete 1082*946379e7Schristosentries, the translation is also uncommented prior to saving. 1083*946379e7Schristos 1084*946379e7Schristos</P> 1085*946379e7Schristos<P> 1086*946379e7Schristos<A NAME="IDX435"></A> 1087*946379e7Schristos<A NAME="IDX436"></A> 1088*946379e7SchristosThe command <KBD>y</KBD> (<CODE>po-yank-msgstr</CODE>) completely replaces the 1089*946379e7Schristostranslation of the current entry by a string taken from the kill ring. 1090*946379e7SchristosFollowing Emacs terminology, we then say that the replacement 1091*946379e7Schristosstring is <EM>yanked</EM> into the PO file buffer. 1092*946379e7SchristosSee section ‘Yanking’ in <CITE>The Emacs Editor</CITE>. 1093*946379e7SchristosThe first time <KBD>y</KBD> is used, the translation receives the value of 1094*946379e7Schristosthe most recent addition to the kill ring. If <KBD>y</KBD> is typed once 1095*946379e7Schristosagain, immediately, without intervening keystrokes, the translation 1096*946379e7Schristosjust inserted is taken away and replaced by the second most recent 1097*946379e7Schristosaddition to the kill ring. By repeating <KBD>y</KBD> many times in a row, 1098*946379e7Schristosthe translator may travel along the kill ring for saved strings, 1099*946379e7Schristosuntil she finds the string she really wanted. 1100*946379e7Schristos 1101*946379e7Schristos</P> 1102*946379e7Schristos<P> 1103*946379e7SchristosWhen a string is yanked into a PO file entry, it is fully and 1104*946379e7Schristosautomatically requoted for complying with the format PO files should 1105*946379e7Schristoshave. Further, if the entry is obsolete, PO mode then appropriately 1106*946379e7Schristospush the inserted string inside comments. Once again, translators 1107*946379e7Schristosshould not burden themselves with quoting considerations besides, of 1108*946379e7Schristoscourse, the necessity of the translated string itself respective to 1109*946379e7Schristosthe program using it. 1110*946379e7Schristos 1111*946379e7Schristos</P> 1112*946379e7Schristos<P> 1113*946379e7SchristosNote that <KBD>k</KBD> or <KBD>w</KBD> are not the only commands pushing strings 1114*946379e7Schristoson the kill ring, as almost any PO mode command replacing translation 1115*946379e7Schristosstrings (or the translator comments) automatically saves the old string 1116*946379e7Schristoson the kill ring. The main exceptions to this general rule are the 1117*946379e7Schristosyanking commands themselves. 1118*946379e7Schristos 1119*946379e7Schristos</P> 1120*946379e7Schristos<P> 1121*946379e7Schristos<A NAME="IDX437"></A> 1122*946379e7SchristosTo better illustrate the operation of killing and yanking, let's 1123*946379e7Schristosuse an actual example, taken from a common situation. When the 1124*946379e7Schristosprogrammer slightly modifies some string right in the program, his 1125*946379e7Schristoschange is later reflected in the PO file by the appearance 1126*946379e7Schristosof a new untranslated entry for the modified string, and the fact 1127*946379e7Schristosthat the entry translating the original or unmodified string becomes 1128*946379e7Schristosobsolete. In many cases, the translator might spare herself some work 1129*946379e7Schristosby retrieving the unmodified translation from the obsolete entry, 1130*946379e7Schristosthen initializing the untranslated entry <CODE>msgstr</CODE> field with 1131*946379e7Schristosthis retrieved translation. Once this done, the obsolete entry is 1132*946379e7Schristosnot wanted anymore, and may be safely deleted. 1133*946379e7Schristos 1134*946379e7Schristos</P> 1135*946379e7Schristos<P> 1136*946379e7SchristosWhen the translator finds an untranslated entry and suspects that a 1137*946379e7Schristosslight variant of the translation exists, she immediately uses <KBD>m</KBD> 1138*946379e7Schristosto mark the current entry location, then starts chasing obsolete 1139*946379e7Schristosentries with <KBD>o</KBD>, hoping to find some translation corresponding 1140*946379e7Schristosto the unmodified string. Once found, she uses the <KBD><KBD>DEL</KBD></KBD> command 1141*946379e7Schristosfor deleting the obsolete entry, knowing that <KBD><KBD>DEL</KBD></KBD> also <EM>kills</EM> 1142*946379e7Schristosthe translation, that is, pushes the translation on the kill ring. 1143*946379e7SchristosThen, <KBD>r</KBD> returns to the initial untranslated entry, and <KBD>y</KBD> 1144*946379e7Schristosthen <EM>yanks</EM> the saved translation right into the <CODE>msgstr</CODE> 1145*946379e7Schristosfield. The translator is then free to use <KBD><KBD>RET</KBD></KBD> for fine 1146*946379e7Schristostuning the translation contents, and maybe to later use <KBD>u</KBD>, 1147*946379e7Schristosthen <KBD>m</KBD> again, for going on with the next untranslated string. 1148*946379e7Schristos 1149*946379e7Schristos</P> 1150*946379e7Schristos<P> 1151*946379e7SchristosWhen some sequence of keys has to be typed over and over again, the 1152*946379e7Schristostranslator may find it useful to become better acquainted with the Emacs 1153*946379e7Schristoscapability of learning these sequences and playing them back under request. 1154*946379e7SchristosSee section ‘Keyboard Macros’ in <CITE>The Emacs Editor</CITE>. 1155*946379e7Schristos 1156*946379e7Schristos</P> 1157*946379e7Schristos 1158*946379e7Schristos 1159*946379e7Schristos<H3><A NAME="SEC62" HREF="gettext_toc.html#TOC62">8.3.10 Modifying Comments</A></H3> 1160*946379e7Schristos<P> 1161*946379e7Schristos<A NAME="IDX438"></A> 1162*946379e7Schristos<A NAME="IDX439"></A> 1163*946379e7Schristos 1164*946379e7Schristos</P> 1165*946379e7Schristos<P> 1166*946379e7SchristosAny translation work done seriously will raise many linguistic 1167*946379e7Schristosdifficulties, for which decisions have to be made, and the choices 1168*946379e7Schristosfurther documented. These documents may be saved within the 1169*946379e7SchristosPO file in form of translator comments, which the translator 1170*946379e7Schristosis free to create, delete, or modify at will. These comments may 1171*946379e7Schristosbe useful to herself when she returns to this PO file after a while. 1172*946379e7Schristos 1173*946379e7Schristos</P> 1174*946379e7Schristos<P> 1175*946379e7SchristosComments not having whitespace after the initial <SAMP>‘#’</SAMP>, for example, 1176*946379e7Schristosthose beginning with <SAMP>‘#.’</SAMP> or <SAMP>‘#:’</SAMP>, are <EM>not</EM> translator 1177*946379e7Schristoscomments, they are exclusively created by other <CODE>gettext</CODE> tools. 1178*946379e7SchristosSo, the commands below will never alter such system added comments, 1179*946379e7Schristosthey are not meant for the translator to modify. See section <A HREF="gettext_3.html#SEC10">3 The Format of PO Files</A>. 1180*946379e7Schristos 1181*946379e7Schristos</P> 1182*946379e7Schristos<P> 1183*946379e7SchristosThe following commands are somewhat similar to those modifying translations, 1184*946379e7Schristosso the general indications given for those apply here. See section <A HREF="gettext_8.html#SEC61">8.3.9 Modifying Translations</A>. 1185*946379e7Schristos 1186*946379e7Schristos</P> 1187*946379e7Schristos<DL COMPACT> 1188*946379e7Schristos 1189*946379e7Schristos<DT><KBD>#</KBD> 1190*946379e7Schristos<DD> 1191*946379e7Schristos<A NAME="IDX440"></A> 1192*946379e7SchristosInteractively edit the translator comments (<CODE>po-edit-comment</CODE>). 1193*946379e7Schristos 1194*946379e7Schristos<DT><KBD>K</KBD> 1195*946379e7Schristos<DD> 1196*946379e7Schristos<A NAME="IDX441"></A> 1197*946379e7SchristosSave the translator comments on the kill ring, and delete it 1198*946379e7Schristos(<CODE>po-kill-comment</CODE>). 1199*946379e7Schristos 1200*946379e7Schristos<DT><KBD>W</KBD> 1201*946379e7Schristos<DD> 1202*946379e7Schristos<A NAME="IDX442"></A> 1203*946379e7SchristosSave the translator comments on the kill ring, without deleting it 1204*946379e7Schristos(<CODE>po-kill-ring-save-comment</CODE>). 1205*946379e7Schristos 1206*946379e7Schristos<DT><KBD>Y</KBD> 1207*946379e7Schristos<DD> 1208*946379e7Schristos<A NAME="IDX443"></A> 1209*946379e7SchristosReplace the translator comments, taking the new from the kill ring 1210*946379e7Schristos(<CODE>po-yank-comment</CODE>). 1211*946379e7Schristos 1212*946379e7Schristos</DL> 1213*946379e7Schristos 1214*946379e7Schristos<P> 1215*946379e7SchristosThese commands parallel PO mode commands for modifying the translation 1216*946379e7Schristosstrings, and behave much the same way as they do, except that they handle 1217*946379e7Schristosthis part of PO file comments meant for translator usage, rather 1218*946379e7Schristosthan the translation strings. So, if the descriptions given below are 1219*946379e7Schristosslightly succinct, it is because the full details have already been given. 1220*946379e7SchristosSee section <A HREF="gettext_8.html#SEC61">8.3.9 Modifying Translations</A>. 1221*946379e7Schristos 1222*946379e7Schristos</P> 1223*946379e7Schristos<P> 1224*946379e7Schristos<A NAME="IDX444"></A> 1225*946379e7Schristos<A NAME="IDX445"></A> 1226*946379e7SchristosThe command <KBD>#</KBD> (<CODE>po-edit-comment</CODE>) opens a new Emacs window 1227*946379e7Schristoscontaining a copy of the translator comments on the current PO file entry. 1228*946379e7SchristosIf there are no such comments, PO mode understands that the translator wants 1229*946379e7Schristosto add a comment to the entry, and she is presented with an empty screen. 1230*946379e7SchristosComment marks (<CODE>#</CODE>) and the space following them are automatically 1231*946379e7Schristosremoved before edition, and reinstated after. For translator comments 1232*946379e7Schristospertaining to obsolete entries, the uncommenting and recommenting operations 1233*946379e7Schristosare done twice. Once in the editing window, the keys <KBD>C-c C-c</KBD> 1234*946379e7Schristosallow the translator to tell she is finished with editing the comment. 1235*946379e7SchristosSee section <A HREF="gettext_8.html#SEC63">8.3.11 Details of Sub Edition</A>, for further details. 1236*946379e7Schristos 1237*946379e7Schristos</P> 1238*946379e7Schristos<P> 1239*946379e7Schristos<A NAME="IDX446"></A> 1240*946379e7SchristosFunctions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after 1241*946379e7Schristosthe string has been inserted in the edit buffer. 1242*946379e7Schristos 1243*946379e7Schristos</P> 1244*946379e7Schristos<P> 1245*946379e7Schristos<A NAME="IDX447"></A> 1246*946379e7Schristos<A NAME="IDX448"></A> 1247*946379e7Schristos<A NAME="IDX449"></A> 1248*946379e7Schristos<A NAME="IDX450"></A> 1249*946379e7Schristos<A NAME="IDX451"></A> 1250*946379e7Schristos<A NAME="IDX452"></A> 1251*946379e7SchristosThe command <KBD>K</KBD> (<CODE>po-kill-comment</CODE>) gets rid of all 1252*946379e7Schristostranslator comments, while saving those comments on the kill ring. 1253*946379e7SchristosThe command <KBD>W</KBD> (<CODE>po-kill-ring-save-comment</CODE>) takes 1254*946379e7Schristosa copy of the translator comments on the kill ring, but leaves 1255*946379e7Schristosthem undisturbed in the current entry. The command <KBD>Y</KBD> 1256*946379e7Schristos(<CODE>po-yank-comment</CODE>) completely replaces the translator comments 1257*946379e7Schristosby a string taken at the front of the kill ring. When this command 1258*946379e7Schristosis immediately repeated, the comments just inserted are withdrawn, 1259*946379e7Schristosand replaced by other strings taken along the kill ring. 1260*946379e7Schristos 1261*946379e7Schristos</P> 1262*946379e7Schristos<P> 1263*946379e7SchristosOn the kill ring, all strings have the same nature. There is no 1264*946379e7Schristosdistinction between <EM>translation</EM> strings and <EM>translator 1265*946379e7Schristoscomments</EM> strings. So, for example, let's presume the translator 1266*946379e7Schristoshas just finished editing a translation, and wants to create a new 1267*946379e7Schristostranslator comment to document why the previous translation was 1268*946379e7Schristosnot good, just to remember what was the problem. Foreseeing that she 1269*946379e7Schristoswill do that in her documentation, the translator may want to quote 1270*946379e7Schristosthe previous translation in her translator comments. To do so, she 1271*946379e7Schristosmay initialize the translator comments with the previous translation, 1272*946379e7Schristosstill at the head of the kill ring. Because editing already pushed the 1273*946379e7Schristosprevious translation on the kill ring, she merely has to type <KBD>M-w</KBD> 1274*946379e7Schristosprior to <KBD>#</KBD>, and the previous translation will be right there, 1275*946379e7Schristosall ready for being introduced by some explanatory text. 1276*946379e7Schristos 1277*946379e7Schristos</P> 1278*946379e7Schristos<P> 1279*946379e7SchristosOn the other hand, presume there are some translator comments already 1280*946379e7Schristosand that the translator wants to add to those comments, instead 1281*946379e7Schristosof wholly replacing them. Then, she should edit the comment right 1282*946379e7Schristosaway with <KBD>#</KBD>. Once inside the editing window, she can use the 1283*946379e7Schristosregular Emacs commands <KBD>C-y</KBD> (<CODE>yank</CODE>) and <KBD>M-y</KBD> 1284*946379e7Schristos(<CODE>yank-pop</CODE>) to get the previous translation where she likes. 1285*946379e7Schristos 1286*946379e7Schristos</P> 1287*946379e7Schristos 1288*946379e7Schristos 1289*946379e7Schristos<H3><A NAME="SEC63" HREF="gettext_toc.html#TOC63">8.3.11 Details of Sub Edition</A></H3> 1290*946379e7Schristos<P> 1291*946379e7Schristos<A NAME="IDX453"></A> 1292*946379e7Schristos 1293*946379e7Schristos</P> 1294*946379e7Schristos<P> 1295*946379e7SchristosThe PO subedit minor mode has a few peculiarities worth being described 1296*946379e7Schristosin fuller detail. It installs a few commands over the usual editing set 1297*946379e7Schristosof Emacs, which are described below. 1298*946379e7Schristos 1299*946379e7Schristos</P> 1300*946379e7Schristos<DL COMPACT> 1301*946379e7Schristos 1302*946379e7Schristos<DT><KBD>C-c C-c</KBD> 1303*946379e7Schristos<DD> 1304*946379e7Schristos<A NAME="IDX454"></A> 1305*946379e7SchristosComplete edition (<CODE>po-subedit-exit</CODE>). 1306*946379e7Schristos 1307*946379e7Schristos<DT><KBD>C-c C-k</KBD> 1308*946379e7Schristos<DD> 1309*946379e7Schristos<A NAME="IDX455"></A> 1310*946379e7SchristosAbort edition (<CODE>po-subedit-abort</CODE>). 1311*946379e7Schristos 1312*946379e7Schristos<DT><KBD>C-c C-a</KBD> 1313*946379e7Schristos<DD> 1314*946379e7Schristos<A NAME="IDX456"></A> 1315*946379e7SchristosConsult auxiliary PO files (<CODE>po-subedit-cycle-auxiliary</CODE>). 1316*946379e7Schristos 1317*946379e7Schristos</DL> 1318*946379e7Schristos 1319*946379e7Schristos<P> 1320*946379e7Schristos<A NAME="IDX457"></A> 1321*946379e7Schristos<A NAME="IDX458"></A> 1322*946379e7Schristos<A NAME="IDX459"></A> 1323*946379e7SchristosThe window's contents represents a translation for a given message, 1324*946379e7Schristosor a translator comment. The translator may modify this window to 1325*946379e7Schristosher heart's content. Once this is done, the command <KBD>C-c C-c</KBD> 1326*946379e7Schristos(<CODE>po-subedit-exit</CODE>) may be used to return the edited translation into 1327*946379e7Schristosthe PO file, replacing the original translation, even if it moved out of 1328*946379e7Schristossight or if buffers were switched. 1329*946379e7Schristos 1330*946379e7Schristos</P> 1331*946379e7Schristos<P> 1332*946379e7Schristos<A NAME="IDX460"></A> 1333*946379e7Schristos<A NAME="IDX461"></A> 1334*946379e7SchristosIf the translator becomes unsatisfied with her translation or comment, 1335*946379e7Schristosto the extent she prefers keeping what was existent prior to the 1336*946379e7Schristos<KBD><KBD>RET</KBD></KBD> or <KBD>#</KBD> command, she may use the command <KBD>C-c C-k</KBD> 1337*946379e7Schristos(<CODE>po-subedit-abort</CODE>) to merely get rid of edition, while preserving 1338*946379e7Schristosthe original translation or comment. Another way would be for her to exit 1339*946379e7Schristosnormally with <KBD>C-c C-c</KBD>, then type <CODE>U</CODE> once for undoing the 1340*946379e7Schristoswhole effect of last edition. 1341*946379e7Schristos 1342*946379e7Schristos</P> 1343*946379e7Schristos<P> 1344*946379e7Schristos<A NAME="IDX462"></A> 1345*946379e7Schristos<A NAME="IDX463"></A> 1346*946379e7SchristosThe command <KBD>C-c C-a</KBD> (<CODE>po-subedit-cycle-auxiliary</CODE>) 1347*946379e7Schristosallows for glancing through translations 1348*946379e7Schristosalready achieved in other languages, directly while editing the current 1349*946379e7Schristostranslation. This may be quite convenient when the translator is fluent 1350*946379e7Schristosat many languages, but of course, only makes sense when such completed 1351*946379e7Schristosauxiliary PO files are already available to her (see section <A HREF="gettext_8.html#SEC65">8.3.13 Consulting Auxiliary PO Files</A>). 1352*946379e7Schristos 1353*946379e7Schristos</P> 1354*946379e7Schristos<P> 1355*946379e7SchristosFunctions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after 1356*946379e7Schristosthe string has been inserted in the edit buffer. 1357*946379e7Schristos 1358*946379e7Schristos</P> 1359*946379e7Schristos<P> 1360*946379e7SchristosWhile editing her translation, the translator should pay attention to not 1361*946379e7Schristosinserting unwanted <KBD><KBD>RET</KBD></KBD> (newline) characters at the end of 1362*946379e7Schristosthe translated string if those are not meant to be there, or to removing 1363*946379e7Schristossuch characters when they are required. Since these characters are not 1364*946379e7Schristosvisible in the editing buffer, they are easily introduced by mistake. 1365*946379e7SchristosTo help her, <KBD><KBD>RET</KBD></KBD> automatically puts the character <CODE><</CODE> 1366*946379e7Schristosat the end of the string being edited, but this <CODE><</CODE> is not really 1367*946379e7Schristospart of the string. On exiting the editing window with <KBD>C-c C-c</KBD>, 1368*946379e7SchristosPO mode automatically removes such <KBD><</KBD> and all whitespace added after 1369*946379e7Schristosit. If the translator adds characters after the terminating <CODE><</CODE>, it 1370*946379e7Schristoslooses its delimiting property and integrally becomes part of the string. 1371*946379e7SchristosIf she removes the delimiting <CODE><</CODE>, then the edited string is taken 1372*946379e7Schristos<EM>as is</EM>, with all trailing newlines, even if invisible. Also, if 1373*946379e7Schristosthe translated string ought to end itself with a genuine <CODE><</CODE>, then 1374*946379e7Schristosthe delimiting <CODE><</CODE> may not be removed; so the string should appear, 1375*946379e7Schristosin the editing window, as ending with two <CODE><</CODE> in a row. 1376*946379e7Schristos 1377*946379e7Schristos</P> 1378*946379e7Schristos<P> 1379*946379e7Schristos<A NAME="IDX464"></A> 1380*946379e7SchristosWhen a translation (or a comment) is being edited, the translator may move 1381*946379e7Schristosthe cursor back into the PO file buffer and freely move to other entries, 1382*946379e7Schristosbrowsing at will. If, with an edition pending, the translator wanders in the 1383*946379e7SchristosPO file buffer, she may decide to start modifying another entry. Each entry 1384*946379e7Schristosbeing edited has its own subedit buffer. It is possible to simultaneously 1385*946379e7Schristosedit the translation <EM>and</EM> the comment of a single entry, or to 1386*946379e7Schristosedit entries in different PO files, all at once. Typing <KBD><KBD>RET</KBD></KBD> 1387*946379e7Schristoson a field already being edited merely resumes that particular edit. Yet, 1388*946379e7Schristosthe translator should better be comfortable at handling many Emacs windows! 1389*946379e7Schristos 1390*946379e7Schristos</P> 1391*946379e7Schristos<P> 1392*946379e7Schristos<A NAME="IDX465"></A> 1393*946379e7SchristosPending subedits may be completed or aborted in any order, regardless 1394*946379e7Schristosof how or when they were started. When many subedits are pending and the 1395*946379e7Schristostranslator asks for quitting the PO file (with the <KBD>q</KBD> command), subedits 1396*946379e7Schristosare automatically resumed one at a time, so she may decide for each of them. 1397*946379e7Schristos 1398*946379e7Schristos</P> 1399*946379e7Schristos 1400*946379e7Schristos 1401*946379e7Schristos<H3><A NAME="SEC64" HREF="gettext_toc.html#TOC64">8.3.12 C Sources Context</A></H3> 1402*946379e7Schristos<P> 1403*946379e7Schristos<A NAME="IDX466"></A> 1404*946379e7Schristos<A NAME="IDX467"></A> 1405*946379e7Schristos<A NAME="IDX468"></A> 1406*946379e7Schristos 1407*946379e7Schristos</P> 1408*946379e7Schristos<P> 1409*946379e7SchristosPO mode is particularly powerful when used with PO files 1410*946379e7Schristoscreated through GNU <CODE>gettext</CODE> utilities, as those utilities 1411*946379e7Schristosinsert special comments in the PO files they generate. 1412*946379e7SchristosSome of these special comments relate the PO file entry to 1413*946379e7Schristosexactly where the untranslated string appears in the program sources. 1414*946379e7Schristos 1415*946379e7Schristos</P> 1416*946379e7Schristos<P> 1417*946379e7SchristosWhen the translator gets to an untranslated entry, she is fairly 1418*946379e7Schristosoften faced with an original string which is not as informative as 1419*946379e7Schristosit normally should be, being succinct, cryptic, or otherwise ambiguous. 1420*946379e7SchristosBefore choosing how to translate the string, she needs to understand 1421*946379e7Schristosbetter what the string really means and how tight the translation has 1422*946379e7Schristosto be. Most of the time, when problems arise, the only way left to make 1423*946379e7Schristosher judgment is looking at the true program sources from where this 1424*946379e7Schristosstring originated, searching for surrounding comments the programmer 1425*946379e7Schristosmight have put in there, and looking around for helping clues of 1426*946379e7Schristos<EM>any</EM> kind. 1427*946379e7Schristos 1428*946379e7Schristos</P> 1429*946379e7Schristos<P> 1430*946379e7SchristosSurely, when looking at program sources, the translator will receive 1431*946379e7Schristosmore help if she is a fluent programmer. However, even if she is 1432*946379e7Schristosnot versed in programming and feels a little lost in C code, the 1433*946379e7Schristostranslator should not be shy at taking a look, once in a while. 1434*946379e7SchristosIt is most probable that she will still be able to find some of the 1435*946379e7Schristoshints she needs. She will learn quickly to not feel uncomfortable 1436*946379e7Schristosin program code, paying more attention to programmer's comments, 1437*946379e7Schristosvariable and function names (if he dared choosing them well), and 1438*946379e7Schristosoverall organization, than to the program code itself. 1439*946379e7Schristos 1440*946379e7Schristos</P> 1441*946379e7Schristos<P> 1442*946379e7Schristos<A NAME="IDX469"></A> 1443*946379e7SchristosThe following commands are meant to help the translator at getting 1444*946379e7Schristosprogram source context for a PO file entry. 1445*946379e7Schristos 1446*946379e7Schristos</P> 1447*946379e7Schristos<DL COMPACT> 1448*946379e7Schristos 1449*946379e7Schristos<DT><KBD>s</KBD> 1450*946379e7Schristos<DD> 1451*946379e7Schristos<A NAME="IDX470"></A> 1452*946379e7SchristosResume the display of a program source context, or cycle through them 1453*946379e7Schristos(<CODE>po-cycle-source-reference</CODE>). 1454*946379e7Schristos 1455*946379e7Schristos<DT><KBD>M-s</KBD> 1456*946379e7Schristos<DD> 1457*946379e7Schristos<A NAME="IDX471"></A> 1458*946379e7SchristosDisplay of a program source context selected by menu 1459*946379e7Schristos(<CODE>po-select-source-reference</CODE>). 1460*946379e7Schristos 1461*946379e7Schristos<DT><KBD>S</KBD> 1462*946379e7Schristos<DD> 1463*946379e7Schristos<A NAME="IDX472"></A> 1464*946379e7SchristosAdd a directory to the search path for source files 1465*946379e7Schristos(<CODE>po-consider-source-path</CODE>). 1466*946379e7Schristos 1467*946379e7Schristos<DT><KBD>M-S</KBD> 1468*946379e7Schristos<DD> 1469*946379e7Schristos<A NAME="IDX473"></A> 1470*946379e7SchristosDelete a directory from the search path for source files 1471*946379e7Schristos(<CODE>po-ignore-source-path</CODE>). 1472*946379e7Schristos 1473*946379e7Schristos</DL> 1474*946379e7Schristos 1475*946379e7Schristos<P> 1476*946379e7Schristos<A NAME="IDX474"></A> 1477*946379e7Schristos<A NAME="IDX475"></A> 1478*946379e7Schristos<A NAME="IDX476"></A> 1479*946379e7Schristos<A NAME="IDX477"></A> 1480*946379e7SchristosThe commands <KBD>s</KBD> (<CODE>po-cycle-source-reference</CODE>) and <KBD>M-s</KBD> 1481*946379e7Schristos(<CODE>po-select-source-reference</CODE>) both open another window displaying 1482*946379e7Schristossome source program file, and already positioned in such a way that 1483*946379e7Schristosit shows an actual use of the string to be translated. By doing 1484*946379e7Schristosso, the command gives source program context for the string. But if 1485*946379e7Schristosthe entry has no source context references, or if all references 1486*946379e7Schristosare unresolved along the search path for program sources, then the 1487*946379e7Schristoscommand diagnoses this as an error. 1488*946379e7Schristos 1489*946379e7Schristos</P> 1490*946379e7Schristos<P> 1491*946379e7SchristosEven if <KBD>s</KBD> (or <KBD>M-s</KBD>) opens a new window, the cursor stays 1492*946379e7Schristosin the PO file window. If the translator really wants to 1493*946379e7Schristosget into the program source window, she ought to do it explicitly, 1494*946379e7Schristosmaybe by using command <KBD>O</KBD>. 1495*946379e7Schristos 1496*946379e7Schristos</P> 1497*946379e7Schristos<P> 1498*946379e7SchristosWhen <KBD>s</KBD> is typed for the first time, or for a PO file entry which 1499*946379e7Schristosis different of the last one used for getting source context, then the 1500*946379e7Schristoscommand reacts by giving the first context available for this entry, 1501*946379e7Schristosif any. If some context has already been recently displayed for the 1502*946379e7Schristoscurrent PO file entry, and the translator wandered off to do other 1503*946379e7Schristosthings, typing <KBD>s</KBD> again will merely resume, in another window, 1504*946379e7Schristosthe context last displayed. In particular, if the translator moved 1505*946379e7Schristosthe cursor away from the context in the source file, the command will 1506*946379e7Schristosbring the cursor back to the context. By using <KBD>s</KBD> many times 1507*946379e7Schristosin a row, with no other commands intervening, PO mode will cycle to 1508*946379e7Schristosthe next available contexts for this particular entry, getting back 1509*946379e7Schristosto the first context once the last has been shown. 1510*946379e7Schristos 1511*946379e7Schristos</P> 1512*946379e7Schristos<P> 1513*946379e7SchristosThe command <KBD>M-s</KBD> behaves differently. Instead of cycling through 1514*946379e7Schristosreferences, it lets the translator choose a particular reference among 1515*946379e7Schristosmany, and displays that reference. It is best used with completion, 1516*946379e7Schristosif the translator types <KBD><KBD>TAB</KBD></KBD> immediately after <KBD>M-s</KBD>, in 1517*946379e7Schristosresponse to the question, she will be offered a menu of all possible 1518*946379e7Schristosreferences, as a reminder of which are the acceptable answers. 1519*946379e7SchristosThis command is useful only where there are really many contexts 1520*946379e7Schristosavailable for a single string to translate. 1521*946379e7Schristos 1522*946379e7Schristos</P> 1523*946379e7Schristos<P> 1524*946379e7Schristos<A NAME="IDX478"></A> 1525*946379e7Schristos<A NAME="IDX479"></A> 1526*946379e7Schristos<A NAME="IDX480"></A> 1527*946379e7Schristos<A NAME="IDX481"></A> 1528*946379e7SchristosProgram source files are usually found relative to where the PO 1529*946379e7Schristosfile stands. As a special provision, when this fails, the file is 1530*946379e7Schristosalso looked for, but relative to the directory immediately above it. 1531*946379e7SchristosThose two cases take proper care of most PO files. However, it might 1532*946379e7Schristoshappen that a PO file has been moved, or is edited in a different 1533*946379e7Schristosplace than its normal location. When this happens, the translator 1534*946379e7Schristosshould tell PO mode in which directory normally sits the genuine PO 1535*946379e7Schristosfile. Many such directories may be specified, and all together, they 1536*946379e7Schristosconstitute what is called the <EM>search path</EM> for program sources. 1537*946379e7SchristosThe command <KBD>S</KBD> (<CODE>po-consider-source-path</CODE>) is used to interactively 1538*946379e7Schristosenter a new directory at the front of the search path, and the command 1539*946379e7Schristos<KBD>M-S</KBD> (<CODE>po-ignore-source-path</CODE>) is used to select, with completion, 1540*946379e7Schristosone of the directories she does not want anymore on the search path. 1541*946379e7Schristos 1542*946379e7Schristos</P> 1543*946379e7Schristos 1544*946379e7Schristos 1545*946379e7Schristos<H3><A NAME="SEC65" HREF="gettext_toc.html#TOC65">8.3.13 Consulting Auxiliary PO Files</A></H3> 1546*946379e7Schristos<P> 1547*946379e7Schristos<A NAME="IDX482"></A> 1548*946379e7Schristos 1549*946379e7Schristos</P> 1550*946379e7Schristos<P> 1551*946379e7SchristosPO mode is able to help the knowledgeable translator, being fluent in 1552*946379e7Schristosmany languages, at taking advantage of translations already achieved 1553*946379e7Schristosin other languages she just happens to know. It provides these other 1554*946379e7Schristoslanguage translations as additional context for her own work. Moreover, 1555*946379e7Schristosit has features to ease the production of translations for many languages 1556*946379e7Schristosat once, for translators preferring to work in this way. 1557*946379e7Schristos 1558*946379e7Schristos</P> 1559*946379e7Schristos<P> 1560*946379e7Schristos<A NAME="IDX483"></A> 1561*946379e7Schristos<A NAME="IDX484"></A> 1562*946379e7SchristosAn <EM>auxiliary</EM> PO file is an existing PO file meant for the same 1563*946379e7Schristospackage the translator is working on, but targeted to a different mother 1564*946379e7Schristostongue language. Commands exist for declaring and handling auxiliary 1565*946379e7SchristosPO files, and also for showing contexts for the entry under work. 1566*946379e7Schristos 1567*946379e7Schristos</P> 1568*946379e7Schristos<P> 1569*946379e7SchristosHere are the auxiliary file commands available in PO mode. 1570*946379e7Schristos 1571*946379e7Schristos</P> 1572*946379e7Schristos<DL COMPACT> 1573*946379e7Schristos 1574*946379e7Schristos<DT><KBD>a</KBD> 1575*946379e7Schristos<DD> 1576*946379e7Schristos<A NAME="IDX485"></A> 1577*946379e7SchristosSeek auxiliary files for another translation for the same entry 1578*946379e7Schristos(<CODE>po-cycle-auxiliary</CODE>). 1579*946379e7Schristos 1580*946379e7Schristos<DT><KBD>C-c C-a</KBD> 1581*946379e7Schristos<DD> 1582*946379e7Schristos<A NAME="IDX486"></A> 1583*946379e7SchristosSwitch to a particular auxiliary file (<CODE>po-select-auxiliary</CODE>). 1584*946379e7Schristos 1585*946379e7Schristos<DT><KBD>A</KBD> 1586*946379e7Schristos<DD> 1587*946379e7Schristos<A NAME="IDX487"></A> 1588*946379e7SchristosDeclare this PO file as an auxiliary file (<CODE>po-consider-as-auxiliary</CODE>). 1589*946379e7Schristos 1590*946379e7Schristos<DT><KBD>M-A</KBD> 1591*946379e7Schristos<DD> 1592*946379e7Schristos<A NAME="IDX488"></A> 1593*946379e7SchristosRemove this PO file from the list of auxiliary files 1594*946379e7Schristos(<CODE>po-ignore-as-auxiliary</CODE>). 1595*946379e7Schristos 1596*946379e7Schristos</DL> 1597*946379e7Schristos 1598*946379e7Schristos<P> 1599*946379e7Schristos<A NAME="IDX489"></A> 1600*946379e7Schristos<A NAME="IDX490"></A> 1601*946379e7Schristos<A NAME="IDX491"></A> 1602*946379e7Schristos<A NAME="IDX492"></A> 1603*946379e7SchristosCommand <KBD>A</KBD> (<CODE>po-consider-as-auxiliary</CODE>) adds the current 1604*946379e7SchristosPO file to the list of auxiliary files, while command <KBD>M-A</KBD> 1605*946379e7Schristos(<CODE>po-ignore-as-auxiliary</CODE> just removes it. 1606*946379e7Schristos 1607*946379e7Schristos</P> 1608*946379e7Schristos<P> 1609*946379e7Schristos<A NAME="IDX493"></A> 1610*946379e7Schristos<A NAME="IDX494"></A> 1611*946379e7SchristosThe command <KBD>a</KBD> (<CODE>po-cycle-auxiliary</CODE>) seeks all auxiliary PO 1612*946379e7Schristosfiles, round-robin, searching for a translated entry in some other language 1613*946379e7Schristoshaving an <CODE>msgid</CODE> field identical as the one for the current entry. 1614*946379e7SchristosThe found PO file, if any, takes the place of the current PO file in 1615*946379e7Schristosthe display (its window gets on top). Before doing so, the current PO 1616*946379e7Schristosfile is also made into an auxiliary file, if not already. So, <KBD>a</KBD> 1617*946379e7Schristosin this newly displayed PO file will seek another PO file, and so on, 1618*946379e7Schristosso repeating <KBD>a</KBD> will eventually yield back the original PO file. 1619*946379e7Schristos 1620*946379e7Schristos</P> 1621*946379e7Schristos<P> 1622*946379e7Schristos<A NAME="IDX495"></A> 1623*946379e7Schristos<A NAME="IDX496"></A> 1624*946379e7SchristosThe command <KBD>C-c C-a</KBD> (<CODE>po-select-auxiliary</CODE>) asks the translator 1625*946379e7Schristosfor her choice of a particular auxiliary file, with completion, and 1626*946379e7Schristosthen switches to that selected PO file. The command also checks if 1627*946379e7Schristosthe selected file has an <CODE>msgid</CODE> field identical as the one for 1628*946379e7Schristosthe current entry, and if yes, this entry becomes current. Otherwise, 1629*946379e7Schristosthe cursor of the selected file is left undisturbed. 1630*946379e7Schristos 1631*946379e7Schristos</P> 1632*946379e7Schristos<P> 1633*946379e7SchristosFor all this to work fully, auxiliary PO files will have to be normalized, 1634*946379e7Schristosin that way that <CODE>msgid</CODE> fields should be written <EM>exactly</EM> 1635*946379e7Schristosthe same way. It is possible to write <CODE>msgid</CODE> fields in various 1636*946379e7Schristosways for representing the same string, different writing would break the 1637*946379e7Schristosproper behaviour of the auxiliary file commands of PO mode. This is not 1638*946379e7Schristosexpected to be much a problem in practice, as most existing PO files have 1639*946379e7Schristostheir <CODE>msgid</CODE> entries written by the same GNU <CODE>gettext</CODE> tools. 1640*946379e7Schristos 1641*946379e7Schristos</P> 1642*946379e7Schristos<P> 1643*946379e7Schristos<A NAME="IDX497"></A> 1644*946379e7SchristosHowever, PO files initially created by PO mode itself, while marking 1645*946379e7Schristosstrings in source files, are normalised differently. So are PO 1646*946379e7Schristosfiles resulting of the <SAMP>‘M-x normalize’</SAMP> command. Until these 1647*946379e7Schristosdiscrepancies between PO mode and other GNU <CODE>gettext</CODE> tools get 1648*946379e7Schristosfully resolved, the translator should stay aware of normalisation issues. 1649*946379e7Schristos 1650*946379e7Schristos</P> 1651*946379e7Schristos 1652*946379e7Schristos 1653*946379e7Schristos<H3><A NAME="SEC66" HREF="gettext_toc.html#TOC66">8.3.14 Using Translation Compendia</A></H3> 1654*946379e7Schristos<P> 1655*946379e7Schristos<A NAME="IDX498"></A> 1656*946379e7Schristos 1657*946379e7Schristos</P> 1658*946379e7Schristos<P> 1659*946379e7Schristos<A NAME="IDX499"></A> 1660*946379e7SchristosA <EM>compendium</EM> is a special PO file containing a set of 1661*946379e7Schristostranslations recurring in many different packages. The translator can 1662*946379e7Schristosuse gettext tools to build a new compendium, to add entries to her 1663*946379e7Schristoscompendium, and to initialize untranslated entries, or to update 1664*946379e7Schristosalready translated entries, from translations kept in the compendium. 1665*946379e7Schristos 1666*946379e7Schristos</P> 1667*946379e7Schristos 1668*946379e7Schristos 1669*946379e7Schristos 1670*946379e7Schristos<H4><A NAME="SEC67" HREF="gettext_toc.html#TOC67">8.3.14.1 Creating Compendia</A></H4> 1671*946379e7Schristos<P> 1672*946379e7Schristos<A NAME="IDX500"></A> 1673*946379e7Schristos<A NAME="IDX501"></A> 1674*946379e7Schristos 1675*946379e7Schristos</P> 1676*946379e7Schristos<P> 1677*946379e7SchristosBasically every PO file consisting of translated entries only can be 1678*946379e7Schristosdeclared as a valid compendium. Often the translator wants to have 1679*946379e7Schristosspecial compendia; let's consider two cases: <CITE>concatenating PO 1680*946379e7Schristosfiles</CITE> and <CITE>extracting a message subset from a PO file</CITE>. 1681*946379e7Schristos 1682*946379e7Schristos</P> 1683*946379e7Schristos 1684*946379e7Schristos 1685*946379e7Schristos<H4><A NAME="SEC68" HREF="gettext_toc.html#TOC68">8.3.14.2 Concatenate PO Files</A></H4> 1686*946379e7Schristos 1687*946379e7Schristos<P> 1688*946379e7Schristos<A NAME="IDX502"></A> 1689*946379e7Schristos<A NAME="IDX503"></A> 1690*946379e7SchristosTo concatenate several valid PO files into one compendium file you can 1691*946379e7Schristosuse <SAMP>‘msgcomm’</SAMP> or <SAMP>‘msgcat’</SAMP> (the latter preferred): 1692*946379e7Schristos 1693*946379e7Schristos</P> 1694*946379e7Schristos 1695*946379e7Schristos<PRE> 1696*946379e7Schristosmsgcat -o compendium.po file1.po file2.po 1697*946379e7Schristos</PRE> 1698*946379e7Schristos 1699*946379e7Schristos<P> 1700*946379e7SchristosBy default, <CODE>msgcat</CODE> will accumulate divergent translations 1701*946379e7Schristosfor the same string. Those occurrences will be marked as <CODE>fuzzy</CODE> 1702*946379e7Schristosand highly visible decorated; calling <CODE>msgcat</CODE> on 1703*946379e7Schristos<TT>‘file1.po’</TT>: 1704*946379e7Schristos 1705*946379e7Schristos</P> 1706*946379e7Schristos 1707*946379e7Schristos<PRE> 1708*946379e7Schristos#: src/hello.c:200 1709*946379e7Schristos#, c-format 1710*946379e7Schristosmsgid "Report bugs to <%s>.\n" 1711*946379e7Schristosmsgstr "Comunicar `bugs' a <%s>.\n" 1712*946379e7Schristos</PRE> 1713*946379e7Schristos 1714*946379e7Schristos<P> 1715*946379e7Schristosand <TT>‘file2.po’</TT>: 1716*946379e7Schristos 1717*946379e7Schristos</P> 1718*946379e7Schristos 1719*946379e7Schristos<PRE> 1720*946379e7Schristos#: src/bye.c:100 1721*946379e7Schristos#, c-format 1722*946379e7Schristosmsgid "Report bugs to <%s>.\n" 1723*946379e7Schristosmsgstr "Comunicar \"bugs\" a <%s>.\n" 1724*946379e7Schristos</PRE> 1725*946379e7Schristos 1726*946379e7Schristos<P> 1727*946379e7Schristoswill result in: 1728*946379e7Schristos 1729*946379e7Schristos</P> 1730*946379e7Schristos 1731*946379e7Schristos<PRE> 1732*946379e7Schristos#: src/hello.c:200 src/bye.c:100 1733*946379e7Schristos#, fuzzy, c-format 1734*946379e7Schristosmsgid "Report bugs to <%s>.\n" 1735*946379e7Schristosmsgstr "" 1736*946379e7Schristos"#-#-#-#-# file1.po #-#-#-#-#\n" 1737*946379e7Schristos"Comunicar `bugs' a <%s>.\n" 1738*946379e7Schristos"#-#-#-#-# file2.po #-#-#-#-#\n" 1739*946379e7Schristos"Comunicar \"bugs\" a <%s>.\n" 1740*946379e7Schristos</PRE> 1741*946379e7Schristos 1742*946379e7Schristos<P> 1743*946379e7SchristosThe translator will have to resolve this “conflict” manually; she 1744*946379e7Schristoshas to decide whether the first or the second version is appropriate 1745*946379e7Schristos(or provide a new translation), to delete the “marker lines”, and 1746*946379e7Schristosfinally to remove the <CODE>fuzzy</CODE> mark. 1747*946379e7Schristos 1748*946379e7Schristos</P> 1749*946379e7Schristos<P> 1750*946379e7SchristosIf the translator knows in advance the first found translation of a 1751*946379e7Schristosmessage is always the best translation she can make use to the 1752*946379e7Schristos<SAMP>‘--use-first’</SAMP> switch: 1753*946379e7Schristos 1754*946379e7Schristos</P> 1755*946379e7Schristos 1756*946379e7Schristos<PRE> 1757*946379e7Schristosmsgcat --use-first -o compendium.po file1.po file2.po 1758*946379e7Schristos</PRE> 1759*946379e7Schristos 1760*946379e7Schristos<P> 1761*946379e7SchristosA good compendium file must not contain <CODE>fuzzy</CODE> or untranslated 1762*946379e7Schristosentries. If input files are “dirty” you must preprocess the input 1763*946379e7Schristosfiles or postprocess the result using <SAMP>‘msgattrib --translated --no-fuzzy’</SAMP>. 1764*946379e7Schristos 1765*946379e7Schristos</P> 1766*946379e7Schristos 1767*946379e7Schristos 1768*946379e7Schristos<H4><A NAME="SEC69" HREF="gettext_toc.html#TOC69">8.3.14.3 Extract a Message Subset from a PO File</A></H4> 1769*946379e7Schristos<P> 1770*946379e7Schristos<A NAME="IDX504"></A> 1771*946379e7Schristos 1772*946379e7Schristos</P> 1773*946379e7Schristos<P> 1774*946379e7SchristosNobody wants to translate the same messages again and again; thus you 1775*946379e7Schristosmay wish to have a compendium file containing <TT>‘getopt.c’</TT> messages. 1776*946379e7Schristos 1777*946379e7Schristos</P> 1778*946379e7Schristos<P> 1779*946379e7SchristosTo extract a message subset (e.g., all <TT>‘getopt.c’</TT> messages) from an 1780*946379e7Schristosexisting PO file into one compendium file you can use <SAMP>‘msggrep’</SAMP>: 1781*946379e7Schristos 1782*946379e7Schristos</P> 1783*946379e7Schristos 1784*946379e7Schristos<PRE> 1785*946379e7Schristosmsggrep --location src/getopt.c -o compendium.po file.po 1786*946379e7Schristos</PRE> 1787*946379e7Schristos 1788*946379e7Schristos 1789*946379e7Schristos 1790*946379e7Schristos<H4><A NAME="SEC70" HREF="gettext_toc.html#TOC70">8.3.14.4 Using Compendia</A></H4> 1791*946379e7Schristos 1792*946379e7Schristos<P> 1793*946379e7SchristosYou can use a compendium file to initialize a translation from scratch 1794*946379e7Schristosor to update an already existing translation. 1795*946379e7Schristos 1796*946379e7Schristos</P> 1797*946379e7Schristos 1798*946379e7Schristos 1799*946379e7Schristos<H4><A NAME="SEC71" HREF="gettext_toc.html#TOC71">8.3.14.5 Initialize a New Translation File</A></H4> 1800*946379e7Schristos<P> 1801*946379e7Schristos<A NAME="IDX505"></A> 1802*946379e7Schristos 1803*946379e7Schristos</P> 1804*946379e7Schristos<P> 1805*946379e7SchristosSince a PO file with translations does not exist the translator can 1806*946379e7Schristosmerely use <TT>‘/dev/null’</TT> to fake the “old” translation file. 1807*946379e7Schristos 1808*946379e7Schristos</P> 1809*946379e7Schristos 1810*946379e7Schristos<PRE> 1811*946379e7Schristosmsgmerge --compendium compendium.po -o file.po /dev/null file.pot 1812*946379e7Schristos</PRE> 1813*946379e7Schristos 1814*946379e7Schristos 1815*946379e7Schristos 1816*946379e7Schristos<H4><A NAME="SEC72" HREF="gettext_toc.html#TOC72">8.3.14.6 Update an Existing Translation File</A></H4> 1817*946379e7Schristos<P> 1818*946379e7Schristos<A NAME="IDX506"></A> 1819*946379e7Schristos 1820*946379e7Schristos</P> 1821*946379e7Schristos<P> 1822*946379e7SchristosConcatenate the compendium file(s) and the existing PO, merge the 1823*946379e7Schristosresult with the POT file and remove the obsolete entries (optional, 1824*946379e7Schristoshere done using <SAMP>‘sed’</SAMP>): 1825*946379e7Schristos 1826*946379e7Schristos</P> 1827*946379e7Schristos 1828*946379e7Schristos<PRE> 1829*946379e7Schristosmsgcat --use-first -o update.po compendium1.po compendium2.po file.po 1830*946379e7Schristosmsgmerge update.po file.pot | sed -e '/^#~/d' > file.po 1831*946379e7Schristos</PRE> 1832*946379e7Schristos 1833*946379e7Schristos<P><HR><P> 1834*946379e7SchristosGo 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*946379e7Schristos</BODY> 1836*946379e7Schristos</HTML> 1837