| 1 | <HTML> |
| 2 | <HEAD> |
| 3 | <!-- This HTML file has been created by texi2html 1.54 |
| 4 | from gettext.texi on 25 January 1999 --> |
| 5 | |
| 6 | <TITLE>GNU gettext utilities - Updating Existing PO Files</TITLE> |
| 7 | <link href="gettext_6.html" rel=Next> |
| 8 | <link href="gettext_4.html" rel=Previous> |
| 9 | <link href="gettext_toc.html" rel=ToC> |
| 10 | |
| 11 | </HEAD> |
| 12 | <BODY> |
| 13 | <p>Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. |
| 14 | <P><HR><P> |
| 15 | |
| 16 | |
| 17 | <H1><A NAME="SEC23" HREF="gettext_toc.html#TOC23">Updating Existing PO Files</A></H1> |
| 18 | |
| 19 | |
| 20 | |
| 21 | <H2><A NAME="SEC24" HREF="gettext_toc.html#TOC24">Invoking the <CODE>msgmerge</CODE> Program</A></H2> |
| 22 | |
| 23 | |
| 24 | |
| 25 | <H2><A NAME="SEC25" HREF="gettext_toc.html#TOC25">Translated Entries</A></H2> |
| 26 | |
| 27 | <P> |
| 28 | Each PO file entry for which the <CODE>msgstr</CODE> field has been filled with |
| 29 | a translation, and which is not marked as fuzzy (see section <A HREF="gettext_5.html#SEC26">Fuzzy Entries</A>), |
| 30 | is a said to be a <STRONG>translated</STRONG> entry. Only translated entries will |
| 31 | later be compiled by GNU <CODE>msgfmt</CODE> and become usable in programs. |
| 32 | Other entry types will be excluded; translation will not occur for them. |
| 33 | |
| 34 | </P> |
| 35 | <P> |
| 36 | Some commands are more specifically related to translated entry processing. |
| 37 | |
| 38 | </P> |
| 39 | <DL COMPACT> |
| 40 | |
| 41 | <DT><KBD>t</KBD> |
| 42 | <DD> |
| 43 | Find the next translated entry. |
| 44 | |
| 45 | <DT><KBD>M-t</KBD> |
| 46 | <DD> |
| 47 | Find the previous translated entry. |
| 48 | |
| 49 | </DL> |
| 50 | |
| 51 | <P> |
| 52 | The commands <KBD>t</KBD> (<CODE>po-next-translated-entry</CODE>) and <KBD>M-t</KBD> |
| 53 | (<CODE>po-previous-transted-entry</CODE>) move forwards or backwards, chasing |
| 54 | for an translated entry. If none is found, the search is extended and |
| 55 | wraps around in the PO file buffer. |
| 56 | |
| 57 | </P> |
| 58 | <P> |
| 59 | Translated entries usually result from the translator having edited in |
| 60 | a translation for them, section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>. However, if the |
| 61 | variable <CODE>po-auto-fuzzy-on-edit</CODE> is not <CODE>nil</CODE>, the entry having |
| 62 | received a new translation first becomes a fuzzy entry, which ought to |
| 63 | be later unfuzzied before becoming an official, genuine translated entry. |
| 64 | See section <A HREF="gettext_5.html#SEC26">Fuzzy Entries</A>. |
| 65 | |
| 66 | </P> |
| 67 | |
| 68 | |
| 69 | <H2><A NAME="SEC26" HREF="gettext_toc.html#TOC26">Fuzzy Entries</A></H2> |
| 70 | |
| 71 | <P> |
| 72 | Each PO file entry may have a set of <STRONG>attributes</STRONG>, which are |
| 73 | qualities given an name and explicitely associated with the entry |
| 74 | translation, using a special system comment. One of these attributes |
| 75 | has the name <CODE>fuzzy</CODE>, and entries having this attribute are said |
| 76 | to have a fuzzy translation. They are called fuzzy entries, for short. |
| 77 | |
| 78 | </P> |
| 79 | <P> |
| 80 | Fuzzy entries, even if they account for translated entries for |
| 81 | most other purposes, usually call for revision by the translator. |
| 82 | Those may be produced by applying the program <CODE>msgmerge</CODE> to |
| 83 | update an older translated PO files according to a new PO template |
| 84 | file, when this tool hypothesises that some new <CODE>msgid</CODE> has |
| 85 | been modified only slightly out of an older one, and chooses to pair |
| 86 | what it thinks to be the old translation for the new modified entry. |
| 87 | The slight alteration in the original string (the <CODE>msgid</CODE> string) |
| 88 | should often be reflected in the translated string, and this requires |
| 89 | the intervention of the translator. For this reason, <CODE>msgmerge</CODE> |
| 90 | might mark some entries as being fuzzy. |
| 91 | |
| 92 | </P> |
| 93 | <P> |
| 94 | Also, the translator may decide herself to mark an entry as fuzzy |
| 95 | for her own convenience, when she wants to remember that the entry |
| 96 | has to be later revisited. So, some commands are more specifically |
| 97 | related to fuzzy entry processing. |
| 98 | |
| 99 | </P> |
| 100 | <DL COMPACT> |
| 101 | |
| 102 | <DT><KBD>f</KBD> |
| 103 | <DD> |
| 104 | Find the next fuzzy entry. |
| 105 | |
| 106 | <DT><KBD>M-f</KBD> |
| 107 | <DD> |
| 108 | Find the previous fuzzy entry. |
| 109 | |
| 110 | <DT><KBD>TAB</KBD> |
| 111 | <DD> |
| 112 | Remove the fuzzy attribute of the current entry. |
| 113 | |
| 114 | </DL> |
| 115 | |
| 116 | <P> |
| 117 | The commands <KBD>f</KBD> (<CODE>po-next-fuzzy</CODE>) and <KBD>M-f</KBD> |
| 118 | (<CODE>po-previous-fuzzy</CODE>) move forwards or backwards, chasing for |
| 119 | a fuzzy entry. If none is found, the search is extended and wraps |
| 120 | around in the PO file buffer. |
| 121 | |
| 122 | </P> |
| 123 | <P> |
| 124 | The command <KBD>TAB</KBD> (<CODE>po-unfuzzy</CODE>) removes the fuzzy |
| 125 | attribute associated with an entry, usually leaving it translated. |
| 126 | Further, if the variable <CODE>po-auto-select-on-unfuzzy</CODE> has not |
| 127 | the <CODE>nil</CODE> value, the <KBD>TAB</KBD> command will automatically chase |
| 128 | for another interesting entry to work on. The initial value of |
| 129 | <CODE>po-auto-select-on-unfuzzy</CODE> is <CODE>nil</CODE>. |
| 130 | |
| 131 | </P> |
| 132 | <P> |
| 133 | The initial value of <CODE>po-auto-fuzzy-on-edit</CODE> is <CODE>nil</CODE>. However, |
| 134 | if the variable <CODE>po-auto-fuzzy-on-edit</CODE> is set to <CODE>t</CODE>, any entry |
| 135 | edited through the <KBD>RET</KBD> command is marked fuzzy, as a way to ensure |
| 136 | some kind of double check, later. In this case, the usual paradigm is |
| 137 | that an entry becomes fuzzy (if not already) whenever the translator |
| 138 | modifies it. If she is satisfied with the translation, she then uses |
| 139 | <KBD>TAB</KBD> to pick another entry to work on, clearing the fuzzy attribute |
| 140 | on the same blow. If she is not satisfied yet, she merely uses <KBD>SPC</KBD> |
| 141 | to chase another entry, leaving the entry fuzzy. |
| 142 | |
| 143 | </P> |
| 144 | <P> |
| 145 | The translator may also use the <KBD>DEL</KBD> command |
| 146 | (<CODE>po-fade-out-entry</CODE>) over any translated entry to mark it as being |
| 147 | fuzzy, when she wants to easily leave a trace she wants to later return |
| 148 | working at this entry. |
| 149 | |
| 150 | </P> |
| 151 | <P> |
| 152 | Also, when time comes to quit working on a PO file buffer with the <KBD>q</KBD> |
| 153 | command, the translator is asked for confirmation, if fuzzy string |
| 154 | still exists. |
| 155 | |
| 156 | </P> |
| 157 | |
| 158 | |
| 159 | <H2><A NAME="SEC27" HREF="gettext_toc.html#TOC27">Untranslated Entries</A></H2> |
| 160 | |
| 161 | <P> |
| 162 | When <CODE>xgettext</CODE> originally creates a PO file, unless told |
| 163 | otherwise, it initializes the <CODE>msgid</CODE> field with the untranslated |
| 164 | string, and leaves the <CODE>msgstr</CODE> string to be empty. Such entries, |
| 165 | having an empty translation, are said to be <STRONG>untranslated</STRONG> entries. |
| 166 | Later, when the programmer slightly modifies some string right in |
| 167 | the program, this change is later reflected in the PO file |
| 168 | by the appearance of a new untranslated entry for the modified string. |
| 169 | |
| 170 | </P> |
| 171 | <P> |
| 172 | The usual commands moving from entry to entry consider untranslated |
| 173 | entries on the same level as active entries. Untranslated entries |
| 174 | are easily recognizable by the fact they end with <SAMP>`msgstr ""'</SAMP>. |
| 175 | |
| 176 | </P> |
| 177 | <P> |
| 178 | The work of the translator might be (quite naively) seen as the process |
| 179 | of seeking after an untranslated entry, editing a translation for |
| 180 | it, and repeating these actions until no untranslated entries remain. |
| 181 | Some commands are more specifically related to untranslated entry |
| 182 | processing. |
| 183 | |
| 184 | </P> |
| 185 | <DL COMPACT> |
| 186 | |
| 187 | <DT><KBD>u</KBD> |
| 188 | <DD> |
| 189 | Find the next untranslated entry. |
| 190 | |
| 191 | <DT><KBD>M-u</KBD> |
| 192 | <DD> |
| 193 | Find the previous untranslated entry. |
| 194 | |
| 195 | <DT><KBD>k</KBD> |
| 196 | <DD> |
| 197 | Turn the current entry into an untranslated one. |
| 198 | |
| 199 | </DL> |
| 200 | |
| 201 | <P> |
| 202 | The commands <KBD>u</KBD> (<CODE>po-next-untranslated-entry</CODE>) and <KBD>M-u</KBD> |
| 203 | (<CODE>po-previous-untransted-entry</CODE>) move forwards or backwards, |
| 204 | chasing for an untranslated entry. If none is found, the search is |
| 205 | extended and wraps around in the PO file buffer. |
| 206 | |
| 207 | </P> |
| 208 | <P> |
| 209 | An entry can be turned back into an untranslated entry by |
| 210 | merely emptying its translation, using the command <KBD>k</KBD> |
| 211 | (<CODE>po-kill-msgstr</CODE>). See section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>. |
| 212 | |
| 213 | </P> |
| 214 | <P> |
| 215 | Also, when time comes to quit working on a PO file buffer |
| 216 | with the <KBD>q</KBD> command, the translator is asked for confirmation, |
| 217 | if some untranslated string still exists. |
| 218 | |
| 219 | </P> |
| 220 | |
| 221 | |
| 222 | <H2><A NAME="SEC28" HREF="gettext_toc.html#TOC28">Obsolete Entries</A></H2> |
| 223 | |
| 224 | <P> |
| 225 | By <STRONG>obsolete</STRONG> PO file entries, we mean those entries which are |
| 226 | commented out, usually by <CODE>msgmerge</CODE> when it found that the |
| 227 | translation is not needed anymore by the package being localized. |
| 228 | |
| 229 | </P> |
| 230 | <P> |
| 231 | The usual commands moving from entry to entry consider obsolete |
| 232 | entries on the same level as active entries. Obsolete entries are |
| 233 | easily recognizable by the fact that all their lines start with |
| 234 | <KBD>#</KBD>, even those lines containing <CODE>msgid</CODE> or <CODE>msgstr</CODE>. |
| 235 | |
| 236 | </P> |
| 237 | <P> |
| 238 | Commands exist for emptying the translation or reinitializing it |
| 239 | to the original untranslated string. Commands interfacing with the |
| 240 | kill ring may force some previously saved text into the translation. |
| 241 | The user may interactively edit the translation. All these commands |
| 242 | may apply to obsolete entries, carefully leaving the entry obsolete |
| 243 | after the fact. |
| 244 | |
| 245 | </P> |
| 246 | <P> |
| 247 | Moreover, some commands are more specifically related to obsolete |
| 248 | entry processing. |
| 249 | |
| 250 | </P> |
| 251 | <DL COMPACT> |
| 252 | |
| 253 | <DT><KBD>o</KBD> |
| 254 | <DD> |
| 255 | Find the next obsolete entry. |
| 256 | |
| 257 | <DT><KBD>M-o</KBD> |
| 258 | <DD> |
| 259 | Find the previous obsolete entry. |
| 260 | |
| 261 | <DT><KBD>DEL</KBD> |
| 262 | <DD> |
| 263 | Make an active entry obsolete, or zap out an obsolete entry. |
| 264 | |
| 265 | </DL> |
| 266 | |
| 267 | <P> |
| 268 | The commands <KBD>o</KBD> (<CODE>po-next-obsolete-entry</CODE>) and <KBD>M-o</KBD> |
| 269 | (<CODE>po-previous-obsolete-entry</CODE>) move forwards or backwards, |
| 270 | chasing for an obsolete entry. If none is found, the search is |
| 271 | extended and wraps around in the PO file buffer. |
| 272 | |
| 273 | </P> |
| 274 | <P> |
| 275 | PO mode does not provide ways for un-commenting an obsolete entry |
| 276 | and making it active, because this would reintroduce an original |
| 277 | untranslated string which does not correspond to any marked string |
| 278 | in the program sources. This goes with the philosophy of never |
| 279 | introducing useless <CODE>msgid</CODE> values. |
| 280 | |
| 281 | </P> |
| 282 | <P> |
| 283 | However, it is possible to comment out an active entry, so making |
| 284 | it obsolete. GNU <CODE>gettext</CODE> utilities will later react to the |
| 285 | disappearance of a translation by using the untranslated string. |
| 286 | The command <KBD>DEL</KBD> (<CODE>po-fade-out-entry</CODE>) pushes the current entry |
| 287 | a little further towards annihilation. If the entry is active (it is a |
| 288 | translated entry), then it is first made fuzzy. If it is already fuzzy, |
| 289 | then the entry is merely commented out, with confirmation. If the entry |
| 290 | is already obsolete, then it is completely deleted from the PO file. |
| 291 | It is easy to recycle the translation so deleted into some other PO file |
| 292 | entry, usually one which is untranslated. See section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>. |
| 293 | |
| 294 | </P> |
| 295 | <P> |
| 296 | Here is a quite interesting problem to solve for later development of |
| 297 | PO mode, for those nights you are not sleepy. The idea would be that |
| 298 | PO mode might become bright enough, one of these days, to make good |
| 299 | guesses at retrieving the most probable candidate, among all obsolete |
| 300 | entries, for initializing the translation of a newly appeared string. |
| 301 | I think it might be a quite hard problem to do this algorithmically, as |
| 302 | we have to develop good and efficient measures of string similarity. |
| 303 | Right now, PO mode completely lets the decision to the translator, |
| 304 | when the time comes to find the adequate obsolete translation, it |
| 305 | merely tries to provide handy tools for helping her to do so. |
| 306 | |
| 307 | </P> |
| 308 | |
| 309 | |
| 310 | <H2><A NAME="SEC29" HREF="gettext_toc.html#TOC29">Modifying Translations</A></H2> |
| 311 | |
| 312 | <P> |
| 313 | PO mode prevents direct edition of the PO file, by the usual |
| 314 | means Emacs give for altering a buffer's contents. By doing so, |
| 315 | it pretends helping the translator to avoid little clerical errors |
| 316 | about the overall file format, or the proper quoting of strings, |
| 317 | as those errors would be easily made. Other kinds of errors are |
| 318 | still possible, but some may be caught and diagnosed by the batch |
| 319 | validation process, which the translator may always trigger by the |
| 320 | <KBD>V</KBD> command. For all other errors, the translator has to rely on |
| 321 | her own judgment, and also on the linguistic reports submitted to her |
| 322 | by the users of the translated package, having the same mother tongue. |
| 323 | |
| 324 | </P> |
| 325 | <P> |
| 326 | When the time comes to create a translation, correct an error diagnosed |
| 327 | mechanically or reported by a user, the translators have to resort to |
| 328 | using the following commands for modifying the translations. |
| 329 | |
| 330 | </P> |
| 331 | <DL COMPACT> |
| 332 | |
| 333 | <DT><KBD>RET</KBD> |
| 334 | <DD> |
| 335 | Interactively edit the translation. |
| 336 | |
| 337 | <DT><KBD>LFD</KBD> |
| 338 | <DD> |
| 339 | Reinitialize the translation with the original, untranslated string. |
| 340 | |
| 341 | <DT><KBD>k</KBD> |
| 342 | <DD> |
| 343 | Save the translation on the kill ring, and delete it. |
| 344 | |
| 345 | <DT><KBD>w</KBD> |
| 346 | <DD> |
| 347 | Save the translation on the kill ring, without deleting it. |
| 348 | |
| 349 | <DT><KBD>y</KBD> |
| 350 | <DD> |
| 351 | Replace the translation, taking the new from the kill ring. |
| 352 | |
| 353 | </DL> |
| 354 | |
| 355 | <P> |
| 356 | The command <KBD>RET</KBD> (<CODE>po-edit-msgstr</CODE>) opens a new Emacs window |
| 357 | containing a copy of the translation taken from the current PO file entry, |
| 358 | all ready for edition, fully modifiable and with the complete extent of |
| 359 | GNU Emacs modifying commands. The string is presented to the translator |
| 360 | expunged of all quoting marks, and she will modify the <EM>unquoted</EM> |
| 361 | string in this window to heart's content. Once done, the regular Emacs |
| 362 | command <KBD>M-C-c</KBD> (<CODE>exit-recursive-edit</CODE>) may be used to return the |
| 363 | edited translation into the PO file, replacing the original translation. |
| 364 | The keys <KBD>C-c C-c</KBD> are bound so they have the same effect as |
| 365 | <KBD>M-C-c</KBD>. |
| 366 | |
| 367 | </P> |
| 368 | <P> |
| 369 | If the translator becomes unsatisfied with her translation to the extent |
| 370 | she prefers keeping the translation which was existent prior to the |
| 371 | <KBD>RET</KBD> command, she may use the standard Emacs command <KBD>C-]</KBD> |
| 372 | (<CODE>abort-recursive-edit</CODE>) to merely get rid of edition, while |
| 373 | preserving the original translation. The keys <KBD>C-c C-k</KBD> are |
| 374 | bound so they have the same effect as <KBD>C-]</KBD>. Another way would |
| 375 | be for her to exit normally with <KBD>C-c C-c</KBD>, then type <CODE>U</CODE> |
| 376 | once for undoing the whole effect of last edition. |
| 377 | |
| 378 | </P> |
| 379 | <P> |
| 380 | Functions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after |
| 381 | the string has been inserted in the edit buffer and before recursive edit |
| 382 | is entered. |
| 383 | |
| 384 | </P> |
| 385 | <P> |
| 386 | While editing her translation, the translator should pay attention to |
| 387 | not inserting unwanted <KBD><KBD>RET</KBD></KBD> (carriage returns) characters at |
| 388 | the end of the translated string if those are not meant to be there, |
| 389 | or to removing such characters when they are required. Since these |
| 390 | characters are not visible in the editing buffer, they are easily |
| 391 | introduced by mistake. To help her, <KBD><KBD>RET</KBD></KBD> automatically puts |
| 392 | the character <KBD><</KBD> at the end of the string being edited, but this |
| 393 | <KBD><</KBD> is not really part of the string. On exiting the editing |
| 394 | window with <KBD>C-c C-c</KBD>, PO mode automatically removes such |
| 395 | <KBD><</KBD> and all whitespace added after it. If the translator adds |
| 396 | characters after the terminating <KBD><</KBD>, it looses its delimiting |
| 397 | property and integrally becomes part of the string. If she removes |
| 398 | the delimiting <KBD><</KBD>, then the edited string is taken <EM>as |
| 399 | is</EM>, with all trailing newlines, even if invisible. Also, if the |
| 400 | translated string ought to end itself with a genuine <KBD><</KBD>, then the |
| 401 | delimiting <KBD><</KBD> may not be removed; so the string should appear, |
| 402 | in the editing window, as ending with two <KBD><</KBD> in a row. |
| 403 | |
| 404 | </P> |
| 405 | <P> |
| 406 | When a translation (or a comment) is being edited, the translator |
| 407 | may move the cursor back into the PO file buffer and freely |
| 408 | move to other entries, browsing at will. The edited entry will |
| 409 | be recovered as soon as the edit ceases, because it is this entry |
| 410 | only which is being modified. If, with an edition still opened, the |
| 411 | translator wanders in the PO file buffer, she cannot modify |
| 412 | any other entry. If she tries to, PO mode will react by suggesting |
| 413 | that she abort the current edit, or else, by inviting her to finish |
| 414 | the current edit prior to any other modification. |
| 415 | |
| 416 | </P> |
| 417 | <P> |
| 418 | The command <KBD>LFD</KBD> (<CODE>po-msgid-to-msgstr</CODE>) initializes, or |
| 419 | reinitializes the translation with the original string. This command |
| 420 | is normally used when the translator wants to redo a fresh translation |
| 421 | of the original string, disregarding any previous work. |
| 422 | |
| 423 | </P> |
| 424 | <P> |
| 425 | It is possible to arrange so, whenever editing an untranslated |
| 426 | entry, the <KBD>LFD</KBD> command be automatically executed. If you set |
| 427 | <CODE>po-auto-edit-with-msgid</CODE> to <CODE>t</CODE>, the translation gets |
| 428 | initialised with the original string, in case none exist already. |
| 429 | The default value for <CODE>po-auto-edit-with-msgid</CODE> is <CODE>nil</CODE>. |
| 430 | |
| 431 | </P> |
| 432 | <P> |
| 433 | In fact, whether it is best to start a translation with an empty |
| 434 | string, or rather with a copy of the original string, is a matter of |
| 435 | taste or habit. Sometimes, the source language and the |
| 436 | target language are so different that is simply best to start writing |
| 437 | on an empty page. At other times, the source and target languages |
| 438 | are so close that it would be a waste to retype a number of words |
| 439 | already being written in the original string. A translator may also |
| 440 | like having the original string right under her eyes, as she will |
| 441 | progressively overwrite the original text with the translation, even |
| 442 | if this requires some extra editing work to get rid of the original. |
| 443 | |
| 444 | </P> |
| 445 | <P> |
| 446 | The command <KBD>k</KBD> (<CODE>po-kill-msgstr</CODE>) merely empties the |
| 447 | translation string, so turning the entry into an untranslated |
| 448 | one. But while doing so, its previous contents is put apart in |
| 449 | a special place, known as the kill ring. The command <KBD>w</KBD> |
| 450 | (<CODE>po-kill-ring-save-msgstr</CODE>) has also the effect of taking a |
| 451 | copy of the translation onto the kill ring, but it otherwise leaves |
| 452 | the entry alone, and does <EM>not</EM> remove the translation from the |
| 453 | entry. Both commands use exactly the Emacs kill ring, which is shared |
| 454 | between buffers, and which is well known already to GNU Emacs lovers. |
| 455 | |
| 456 | </P> |
| 457 | <P> |
| 458 | The translator may use <KBD>k</KBD> or <KBD>w</KBD> many times in the course |
| 459 | of her work, as the kill ring may hold several saved translations. |
| 460 | From the kill ring, strings may later be reinserted in various |
| 461 | Emacs buffers. In particular, the kill ring may be used for moving |
| 462 | translation strings between different entries of a single PO file |
| 463 | buffer, or if the translator is handling many such buffers at once, |
| 464 | even between PO files. |
| 465 | |
| 466 | </P> |
| 467 | <P> |
| 468 | To facilitate exchanges with buffers which are not in PO mode, the |
| 469 | translation string put on the kill ring by the <KBD>k</KBD> command is fully |
| 470 | unquoted before being saved: external quotes are removed, multi-lines |
| 471 | strings are concatenated, and backslashed escaped sequences are turned |
| 472 | into their corresponding characters. In the special case of obsolete |
| 473 | entries, the translation is also uncommented prior to saving. |
| 474 | |
| 475 | </P> |
| 476 | <P> |
| 477 | The command <KBD>y</KBD> (<CODE>po-yank-msgstr</CODE>) completely replaces the |
| 478 | translation of the current entry by a string taken from the kill ring. |
| 479 | Following GNU Emacs terminology, we then say that the replacement |
| 480 | string is <STRONG>yanked</STRONG> into the PO file buffer. |
| 481 | See section `Yanking' in <CITE>The Emacs Editor</CITE>. |
| 482 | The first time <KBD>y</KBD> is used, the translation receives the value of |
| 483 | the most recent addition to the kill ring. If <KBD>y</KBD> is typed once |
| 484 | again, immediately, without intervening keystrokes, the translation |
| 485 | just inserted is taken away and replaced by the second most recent |
| 486 | addition to the kill ring. By repeating <KBD>y</KBD> many times in a row, |
| 487 | the translator may travel along the kill ring for saved strings, |
| 488 | until she finds the string she really wanted. |
| 489 | |
| 490 | </P> |
| 491 | <P> |
| 492 | When a string is yanked into a PO file entry, it is fully and |
| 493 | automatically requoted for complying with the format PO files should |
| 494 | have. Further, if the entry is obsolete, PO mode then appropriately |
| 495 | push the inserted string inside comments. Once again, translators |
| 496 | should not burden themselves with quoting considerations besides, of |
| 497 | course, the necessity of the translated string itself respective to |
| 498 | the program using it. |
| 499 | |
| 500 | </P> |
| 501 | <P> |
| 502 | Note that <KBD>k</KBD> or <KBD>w</KBD> are not the only commands pushing strings |
| 503 | on the kill ring, as almost any PO mode command replacing translation |
| 504 | strings (or the translator comments) automatically save the old string |
| 505 | on the kill ring. The main exceptions to this general rule are the |
| 506 | yanking commands themselves. |
| 507 | |
| 508 | </P> |
| 509 | <P> |
| 510 | To better illustrate the operation of killing and yanking, let's |
| 511 | use an actual example, taken from a common situation. When the |
| 512 | programmer slightly modifies some string right in the program, his |
| 513 | change is later reflected in the PO file by the appearance |
| 514 | of a new untranslated entry for the modified string, and the fact |
| 515 | that the entry translating the original or unmodified string becomes |
| 516 | obsolete. In many cases, the translator might spare herself some work |
| 517 | by retrieving the unmodified translation from the obsolete entry, |
| 518 | then initializing the untranslated entry <CODE>msgstr</CODE> field with |
| 519 | this retrieved translation. Once this done, the obsolete entry is |
| 520 | not wanted anymore, and may be safely deleted. |
| 521 | |
| 522 | </P> |
| 523 | <P> |
| 524 | When the translator finds an untranslated entry and suspects that a |
| 525 | slight variant of the translation exists, she immediately uses <KBD>m</KBD> |
| 526 | to mark the current entry location, then starts chasing obsolete |
| 527 | entries with <KBD>o</KBD>, hoping to find some translation corresponding |
| 528 | to the unmodified string. Once found, she uses the <KBD>DEL</KBD> command |
| 529 | for deleting the obsolete entry, knowing that <KBD>DEL</KBD> also <EM>kills</EM> |
| 530 | the translation, that is, pushes the translation on the kill ring. |
| 531 | Then, <KBD>r</KBD> returns to the initial untranslated entry, <KBD>y</KBD> |
| 532 | then <EM>yanks</EM> the saved translation right into the <CODE>msgstr</CODE> |
| 533 | field. The translator is then free to use <KBD><KBD>RET</KBD></KBD> for fine |
| 534 | tuning the translation contents, and maybe to later use <KBD>u</KBD>, |
| 535 | then <KBD>m</KBD> again, for going on with the next untranslated string. |
| 536 | |
| 537 | </P> |
| 538 | <P> |
| 539 | When some sequence of keys has to be typed over and over again, the |
| 540 | translator may find it useful to become better acquainted with the GNU |
| 541 | Emacs capability of learning these sequences and playing them back under |
| 542 | request. See section `Keyboard Macros' in <CITE>The Emacs Editor</CITE>. |
| 543 | |
| 544 | </P> |
| 545 | |
| 546 | |
| 547 | <H2><A NAME="SEC30" HREF="gettext_toc.html#TOC30">Modifying Comments</A></H2> |
| 548 | |
| 549 | <P> |
| 550 | Any translation work done seriously will raise many linguistic |
| 551 | difficulties, for which decisions have to be made, and the choices |
| 552 | further documented. These documents may be saved within the |
| 553 | PO file in form of translator comments, which the translator |
| 554 | is free to create, delete, or modify at will. These comments may |
| 555 | be useful to herself when she returns to this PO file after a while. |
| 556 | |
| 557 | </P> |
| 558 | <P> |
| 559 | Comments not having whitespace after the initial <SAMP>`#'</SAMP>, for example, |
| 560 | those beginning with <SAMP>`#.'</SAMP> or <SAMP>`#:'</SAMP>, are <EM>not</EM> translator |
| 561 | comments, they are exclusively created by other <CODE>gettext</CODE> tools. |
| 562 | So, the commands below will never alter such system added comments, |
| 563 | they are not meant for the translator to modify. See section <A HREF="gettext_2.html#SEC9">The Format of PO Files</A>. |
| 564 | |
| 565 | </P> |
| 566 | <P> |
| 567 | The following commands are somewhat similar to those modifying translations, |
| 568 | so the general indications given for those apply here. See section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>. |
| 569 | |
| 570 | </P> |
| 571 | <DL COMPACT> |
| 572 | |
| 573 | <DT><KBD>#</KBD> |
| 574 | <DD> |
| 575 | Interactively edit the translator comments. |
| 576 | |
| 577 | <DT><KBD>K</KBD> |
| 578 | <DD> |
| 579 | Save the translator comments on the kill ring, and delete it. |
| 580 | |
| 581 | <DT><KBD>W</KBD> |
| 582 | <DD> |
| 583 | Save the translator comments on the kill ring, without deleting it. |
| 584 | |
| 585 | <DT><KBD>Y</KBD> |
| 586 | <DD> |
| 587 | Replace the translator comments, taking the new from the kill ring. |
| 588 | |
| 589 | </DL> |
| 590 | |
| 591 | <P> |
| 592 | These commands parallel PO mode commands for modifying the translation |
| 593 | strings, and behave much the same way as they do, except that they handle |
| 594 | this part of PO file comments meant for translator usage, rather |
| 595 | than the translation strings. So, if the descriptions given below are |
| 596 | slightly succinct, it is because the full details have already been given. |
| 597 | See section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>. |
| 598 | |
| 599 | </P> |
| 600 | <P> |
| 601 | The command <KBD>#</KBD> (<CODE>po-edit-comment</CODE>) opens a new Emacs |
| 602 | window containing a copy of the translator comments on the current |
| 603 | PO file entry. If there are no such comments, PO mode |
| 604 | understands that the translator wants to add a comment to the entry, |
| 605 | and she is presented with an empty screen. Comment marks (<KBD>#</KBD>) and |
| 606 | the space following them are automatically removed before edition, |
| 607 | and reinstated after. For translator comments pertaining to obsolete |
| 608 | entries, the uncommenting and recommenting operations are done twice. |
| 609 | Once in the editing window, the keys <KBD>C-c C-c</KBD> allow the |
| 610 | translator to tell she is finished with editing the comment. |
| 611 | |
| 612 | </P> |
| 613 | <P> |
| 614 | Functions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after |
| 615 | the string has been inserted in the edit buffer and before recursive edit |
| 616 | is entered. |
| 617 | |
| 618 | </P> |
| 619 | <P> |
| 620 | The command <KBD>K</KBD> (<CODE>po-kill-comment</CODE>) get rid of all |
| 621 | translator comments, while saving those comments on the kill ring. |
| 622 | The command <KBD>W</KBD> (<CODE>po-kill-ring-save-comment</CODE>) takes |
| 623 | a copy of the translator comments on the kill ring, but leaves |
| 624 | them undisturbed in the current entry. The command <KBD>Y</KBD> |
| 625 | (<CODE>po-yank-comment</CODE>) completely replaces the translator comments |
| 626 | by a string taken at the front of the kill ring. When this command |
| 627 | is immediately repeated, the comments just inserted are withdrawn, |
| 628 | and replaced by other strings taken along the kill ring. |
| 629 | |
| 630 | </P> |
| 631 | <P> |
| 632 | On the kill ring, all strings have the same nature. There is no |
| 633 | distinction between <EM>translation</EM> strings and <EM>translator |
| 634 | comments</EM> strings. So, for example, let's presume the translator |
| 635 | has just finished editing a translation, and wants to create a new |
| 636 | translator comment to document why the previous translation was |
| 637 | not good, just to remember what was the problem. Foreseeing that she |
| 638 | will do that in her documentation, the translator may want to quote |
| 639 | the previous translation in her translator comments. To do so, she |
| 640 | may initialize the translator comments with the previous translation, |
| 641 | still at the head of the kill ring. Because editing already pushed the |
| 642 | previous translation on the kill ring, she merely has to type <KBD>M-w</KBD> |
| 643 | prior to <KBD>#</KBD>, and the previous translation will be right there, |
| 644 | all ready for being introduced by some explanatory text. |
| 645 | |
| 646 | </P> |
| 647 | <P> |
| 648 | On the other hand, presume there are some translator comments already |
| 649 | and that the translator wants to add to those comments, instead |
| 650 | of wholly replacing them. Then, she should edit the comment right |
| 651 | away with <KBD>#</KBD>. Once inside the editing window, she can use the |
| 652 | regular GNU Emacs commands <KBD>C-y</KBD> (<CODE>yank</CODE>) and <KBD>M-y</KBD> |
| 653 | (<CODE>yank-pop</CODE>) to get the previous translation where she likes. |
| 654 | |
| 655 | </P> |
| 656 | |
| 657 | |
| 658 | <H2><A NAME="SEC31" HREF="gettext_toc.html#TOC31">Consulting Auxiliary PO Files</A></H2> |
| 659 | |
| 660 | <P> |
| 661 | PO mode is able to help the knowledgeable translator, being fluent in |
| 662 | many languages, at taking advantage of translations already achieved |
| 663 | in other languages she just happens to know. It provides these other |
| 664 | language translations as additional context for her own work. Moreover, |
| 665 | it has features to ease the production of translations for many languages |
| 666 | at once, for translators preferring to work in this way. |
| 667 | |
| 668 | </P> |
| 669 | <P> |
| 670 | An <STRONG>auxiliary</STRONG> PO file is an existing PO file meant for the same |
| 671 | package the translator is working on, but targeted to a different mother |
| 672 | tongue language. Commands exist for declaring and handling auxiliary |
| 673 | PO files, and also for showing contexts for the entry under work. |
| 674 | |
| 675 | </P> |
| 676 | <P> |
| 677 | Here are the auxiliary file commands available in PO mode. |
| 678 | |
| 679 | </P> |
| 680 | <DL COMPACT> |
| 681 | |
| 682 | <DT><KBD>a</KBD> |
| 683 | <DD> |
| 684 | Seek auxiliary files for another translation for the same entry. |
| 685 | |
| 686 | <DT><KBD>M-a</KBD> |
| 687 | <DD> |
| 688 | Switch to a particular auxiliary file. |
| 689 | |
| 690 | <DT><KBD>A</KBD> |
| 691 | <DD> |
| 692 | Declare this PO file as an auxiliary file. |
| 693 | |
| 694 | <DT><KBD>M-A</KBD> |
| 695 | <DD> |
| 696 | Remove this PO file from the list of auxiliary files. |
| 697 | |
| 698 | </DL> |
| 699 | |
| 700 | <P> |
| 701 | Command <KBD>A</KBD> (<CODE>po-consider-as-auxiliary</CODE>) adds the current |
| 702 | PO file to the list of auxiliary files, while command <KBD>M-A</KBD> |
| 703 | (<CODE>po-ignore-as-auxiliary</CODE> just removes it. |
| 704 | |
| 705 | </P> |
| 706 | <P> |
| 707 | The command <KBD>a</KBD> (<CODE>po-cycle-auxiliary</CODE>) seeks all auxiliary PO |
| 708 | files, round-robin, searching for a translated entry in some other language |
| 709 | having an <CODE>msgid</CODE> field identical as the one for the current entry. |
| 710 | The found PO file, if any, takes the place of the current PO file in |
| 711 | the display (its window gets on top). Before doing so, the current PO |
| 712 | file is also made into an auxiliary file, if not already. So, <KBD>a</KBD> |
| 713 | in this newly displayed PO file will seek another PO file, and so on, |
| 714 | so repeating <KBD>a</KBD> will eventually yield back the original PO file. |
| 715 | |
| 716 | </P> |
| 717 | <P> |
| 718 | The command <KBD>M-a</KBD> (<CODE>po-select-auxiliary</CODE>) asks the translator |
| 719 | for her choice of a particular auxiliary file, with completion, and |
| 720 | then switches to that selected PO file. The command also checks if |
| 721 | the selected file has an <CODE>msgid</CODE> field identical as the one for |
| 722 | the current entry, and if yes, this entry becomes current. Otherwise, |
| 723 | the cursor of the selected file is left undisturbed. |
| 724 | |
| 725 | </P> |
| 726 | <P> |
| 727 | For all this to work fully, auxiliary PO files will have to be normalized, |
| 728 | in that way that <CODE>msgid</CODE> fields should be written <EM>exactly</EM> |
| 729 | the same way. It is possible to write <CODE>msgid</CODE> fields in various |
| 730 | ways for representing the same string, different writing would break the |
| 731 | proper behaviour of the auxiliary file commands of PO mode. This is not |
| 732 | expected to be much a problem in practice, as most existing PO files have |
| 733 | their <CODE>msgid</CODE> entries written by the same GNU <CODE>gettext</CODE> tools. |
| 734 | |
| 735 | </P> |
| 736 | <P> |
| 737 | However, PO files initially created by PO mode itself, while marking |
| 738 | strings in source files, are normalised differently. So are PO |
| 739 | files resulting of the the <SAMP>`M-x normalize'</SAMP> command. Until these |
| 740 | discrepancies between PO mode and other GNU <CODE>gettext</CODE> tools get |
| 741 | fully resolved, the translator should stay aware of normalisation issues. |
| 742 | |
| 743 | </P> |
| 744 | <P><HR><P> |
| 745 | <p>Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_12.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. |
| 746 | </BODY> |
| 747 | </HTML> |