Go to the first, previous, next, last section, table of contents. +
+ + +
msgmerge Program
+Each PO file entry for which the msgstr field has been filled with
+a translation, and which is not marked as fuzzy (see section Fuzzy Entries),
+is a said to be a translated entry. Only translated entries will
+later be compiled by GNU msgfmt and become usable in programs.
+Other entry types will be excluded; translation will not occur for them.
+
+
+Some commands are more specifically related to translated entry processing. + +
+
+The commands t (po-next-translated-entry) and M-t
+(po-previous-transted-entry) move forwards or backwards, chasing
+for an translated entry. If none is found, the search is extended and
+wraps around in the PO file buffer.
+
+
+Translated entries usually result from the translator having edited in
+a translation for them, section Modifying Translations. However, if the
+variable po-auto-fuzzy-on-edit is not nil, the entry having
+received a new translation first becomes a fuzzy entry, which ought to
+be later unfuzzied before becoming an official, genuine translated entry.
+See section Fuzzy Entries.
+
+
+Each PO file entry may have a set of attributes, which are
+qualities given an name and explicitly associated with the entry
+translation, using a special system comment. One of these attributes
+has the name fuzzy, and entries having this attribute are said
+to have a fuzzy translation. They are called fuzzy entries, for short.
+
+
+Fuzzy entries, even if they account for translated entries for
+most other purposes, usually call for revision by the translator.
+Those may be produced by applying the program msgmerge to
+update an older translated PO files according to a new PO template
+file, when this tool hypothesises that some new msgid has
+been modified only slightly out of an older one, and chooses to pair
+what it thinks to be the old translation for the new modified entry.
+The slight alteration in the original string (the msgid string)
+should often be reflected in the translated string, and this requires
+the intervention of the translator. For this reason, msgmerge
+might mark some entries as being fuzzy.
+
+
+Also, the translator may decide herself to mark an entry as fuzzy +for her own convenience, when she wants to remember that the entry +has to be later revisited. So, some commands are more specifically +related to fuzzy entry processing. + +
+
+The commands f (po-next-fuzzy) and M-f
+(po-previous-fuzzy) move forwards or backwards, chasing for
+a fuzzy entry. If none is found, the search is extended and wraps
+around in the PO file buffer.
+
+
+The command TAB (po-unfuzzy) removes the fuzzy
+attribute associated with an entry, usually leaving it translated.
+Further, if the variable po-auto-select-on-unfuzzy has not
+the nil value, the TAB command will automatically chase
+for another interesting entry to work on. The initial value of
+po-auto-select-on-unfuzzy is nil.
+
+
+The initial value of po-auto-fuzzy-on-edit is nil. However,
+if the variable po-auto-fuzzy-on-edit is set to t, any entry
+edited through the RET command is marked fuzzy, as a way to ensure
+some kind of double check, later. In this case, the usual paradigm is
+that an entry becomes fuzzy (if not already) whenever the translator
+modifies it. If she is satisfied with the translation, she then uses
+TAB to pick another entry to work on, clearing the fuzzy attribute
+on the same blow. If she is not satisfied yet, she merely uses SPC
+to chase another entry, leaving the entry fuzzy.
+
+
+The translator may also use the DEL command
+(po-fade-out-entry) over any translated entry to mark it as being
+fuzzy, when she wants to easily leave a trace she wants to later return
+working at this entry.
+
+
+Also, when time comes to quit working on a PO file buffer with the q +command, the translator is asked for confirmation, if fuzzy string +still exists. + +
+ + +
+When xgettext originally creates a PO file, unless told
+otherwise, it initializes the msgid field with the untranslated
+string, and leaves the msgstr string to be empty. Such entries,
+having an empty translation, are said to be untranslated entries.
+Later, when the programmer slightly modifies some string right in
+the program, this change is later reflected in the PO file
+by the appearance of a new untranslated entry for the modified string.
+
+
+The usual commands moving from entry to entry consider untranslated +entries on the same level as active entries. Untranslated entries +are easily recognizable by the fact they end with `msgstr ""'. + +
++The work of the translator might be (quite naively) seen as the process +of seeking after an untranslated entry, editing a translation for +it, and repeating these actions until no untranslated entries remain. +Some commands are more specifically related to untranslated entry +processing. + +
+
+The commands u (po-next-untranslated-entry) and M-u
+(po-previous-untransted-entry) move forwards or backwards,
+chasing for an untranslated entry. If none is found, the search is
+extended and wraps around in the PO file buffer.
+
+
+An entry can be turned back into an untranslated entry by
+merely emptying its translation, using the command k
+(po-kill-msgstr). See section Modifying Translations.
+
+
+Also, when time comes to quit working on a PO file buffer +with the q command, the translator is asked for confirmation, +if some untranslated string still exists. + +
+ + +
+By obsolete PO file entries, we mean those entries which are
+commented out, usually by msgmerge when it found that the
+translation is not needed anymore by the package being localized.
+
+
+The usual commands moving from entry to entry consider obsolete
+entries on the same level as active entries. Obsolete entries are
+easily recognizable by the fact that all their lines start with
+#, even those lines containing msgid or msgstr.
+
+
+Commands exist for emptying the translation or reinitializing it +to the original untranslated string. Commands interfacing with the +kill ring may force some previously saved text into the translation. +The user may interactively edit the translation. All these commands +may apply to obsolete entries, carefully leaving the entry obsolete +after the fact. + +
++Moreover, some commands are more specifically related to obsolete +entry processing. + +
+
+The commands o (po-next-obsolete-entry) and M-o
+(po-previous-obsolete-entry) move forwards or backwards,
+chasing for an obsolete entry. If none is found, the search is
+extended and wraps around in the PO file buffer.
+
+
+PO mode does not provide ways for un-commenting an obsolete entry
+and making it active, because this would reintroduce an original
+untranslated string which does not correspond to any marked string
+in the program sources. This goes with the philosophy of never
+introducing useless msgid values.
+
+
+However, it is possible to comment out an active entry, so making
+it obsolete. GNU gettext utilities will later react to the
+disappearance of a translation by using the untranslated string.
+The command DEL (po-fade-out-entry) pushes the current entry
+a little further towards annihilation. If the entry is active (it is a
+translated entry), then it is first made fuzzy. If it is already fuzzy,
+then the entry is merely commented out, with confirmation. If the entry
+is already obsolete, then it is completely deleted from the PO file.
+It is easy to recycle the translation so deleted into some other PO file
+entry, usually one which is untranslated. See section Modifying Translations.
+
+
+Here is a quite interesting problem to solve for later development of +PO mode, for those nights you are not sleepy. The idea would be that +PO mode might become bright enough, one of these days, to make good +guesses at retrieving the most probable candidate, among all obsolete +entries, for initializing the translation of a newly appeared string. +I think it might be a quite hard problem to do this algorithmically, as +we have to develop good and efficient measures of string similarity. +Right now, PO mode completely lets the decision to the translator, +when the time comes to find the adequate obsolete translation, it +merely tries to provide handy tools for helping her to do so. + +
+ + ++PO mode prevents direct edition of the PO file, by the usual +means Emacs give for altering a buffer's contents. By doing so, +it pretends helping the translator to avoid little clerical errors +about the overall file format, or the proper quoting of strings, +as those errors would be easily made. Other kinds of errors are +still possible, but some may be caught and diagnosed by the batch +validation process, which the translator may always trigger by the +V command. For all other errors, the translator has to rely on +her own judgment, and also on the linguistic reports submitted to her +by the users of the translated package, having the same mother tongue. + +
++When the time comes to create a translation, correct an error diagnosed +mechanically or reported by a user, the translators have to resort to +using the following commands for modifying the translations. + +
+
+The command RET (po-edit-msgstr) opens a new Emacs window
+containing a copy of the translation taken from the current PO file entry,
+all ready for edition, fully modifiable and with the complete extent of
+GNU Emacs modifying commands. The string is presented to the translator
+expunged of all quoting marks, and she will modify the unquoted
+string in this window to heart's content. Once done, the regular Emacs
+command M-C-c (exit-recursive-edit) may be used to return the
+edited translation into the PO file, replacing the original translation.
+The keys C-c C-c are bound so they have the same effect as
+M-C-c.
+
+
+If the translator becomes unsatisfied with her translation to the extent
+she prefers keeping the translation which was existent prior to the
+RET command, she may use the standard Emacs command C-]
+(abort-recursive-edit) to merely get rid of edition, while
+preserving the original translation. The keys C-c C-k are
+bound so they have the same effect as C-]. Another way would
+be for her to exit normally with C-c C-c, then type U
+once for undoing the whole effect of last edition.
+
+
+Functions found on po-subedit-mode-hook, if any, are executed after
+the string has been inserted in the edit buffer and before recursive edit
+is entered.
+
+
+While editing her translation, the translator should pay attention to +not inserting unwanted RET (carriage returns) characters at +the end of the translated string if those are not meant to be there, +or to removing such characters when they are required. Since these +characters are not visible in the editing buffer, they are easily +introduced by mistake. To help her, RET automatically puts +the character < at the end of the string being edited, but this +< is not really part of the string. On exiting the editing +window with C-c C-c, PO mode automatically removes such +< and all whitespace added after it. If the translator adds +characters after the terminating <, it looses its delimiting +property and integrally becomes part of the string. If she removes +the delimiting <, then the edited string is taken as +is, with all trailing newlines, even if invisible. Also, if the +translated string ought to end itself with a genuine <, then the +delimiting < may not be removed; so the string should appear, +in the editing window, as ending with two < in a row. + +
++When a translation (or a comment) is being edited, the translator +may move the cursor back into the PO file buffer and freely +move to other entries, browsing at will. The edited entry will +be recovered as soon as the edit ceases, because it is this entry +only which is being modified. If, with an edition still opened, the +translator wanders in the PO file buffer, she cannot modify +any other entry. If she tries to, PO mode will react by suggesting +that she abort the current edit, or else, by inviting her to finish +the current edit prior to any other modification. + +
+
+The command LFD (po-msgid-to-msgstr) initializes, or
+reinitializes the translation with the original string. This command
+is normally used when the translator wants to redo a fresh translation
+of the original string, disregarding any previous work.
+
+
+It is possible to arrange so, whenever editing an untranslated
+entry, the LFD command be automatically executed. If you set
+po-auto-edit-with-msgid to t, the translation gets
+initialised with the original string, in case none exist already.
+The default value for po-auto-edit-with-msgid is nil.
+
+
+In fact, whether it is best to start a translation with an empty +string, or rather with a copy of the original string, is a matter of +taste or habit. Sometimes, the source language and the +target language are so different that is simply best to start writing +on an empty page. At other times, the source and target languages +are so close that it would be a waste to retype a number of words +already being written in the original string. A translator may also +like having the original string right under her eyes, as she will +progressively overwrite the original text with the translation, even +if this requires some extra editing work to get rid of the original. + +
+
+The command k (po-kill-msgstr) merely empties the
+translation string, so turning the entry into an untranslated
+one. But while doing so, its previous contents is put apart in
+a special place, known as the kill ring. The command w
+(po-kill-ring-save-msgstr) has also the effect of taking a
+copy of the translation onto the kill ring, but it otherwise leaves
+the entry alone, and does not remove the translation from the
+entry. Both commands use exactly the Emacs kill ring, which is shared
+between buffers, and which is well known already to GNU Emacs lovers.
+
+
+The translator may use k or w many times in the course +of her work, as the kill ring may hold several saved translations. +From the kill ring, strings may later be reinserted in various +Emacs buffers. In particular, the kill ring may be used for moving +translation strings between different entries of a single PO file +buffer, or if the translator is handling many such buffers at once, +even between PO files. + +
++To facilitate exchanges with buffers which are not in PO mode, the +translation string put on the kill ring by the k command is fully +unquoted before being saved: external quotes are removed, multi-lines +strings are concatenated, and backslashed escaped sequences are turned +into their corresponding characters. In the special case of obsolete +entries, the translation is also uncommented prior to saving. + +
+
+The command y (po-yank-msgstr) completely replaces the
+translation of the current entry by a string taken from the kill ring.
+Following GNU Emacs terminology, we then say that the replacement
+string is yanked into the PO file buffer.
+See section `Yanking' in The Emacs Editor.
+The first time y is used, the translation receives the value of
+the most recent addition to the kill ring. If y is typed once
+again, immediately, without intervening keystrokes, the translation
+just inserted is taken away and replaced by the second most recent
+addition to the kill ring. By repeating y many times in a row,
+the translator may travel along the kill ring for saved strings,
+until she finds the string she really wanted.
+
+
+When a string is yanked into a PO file entry, it is fully and +automatically requoted for complying with the format PO files should +have. Further, if the entry is obsolete, PO mode then appropriately +push the inserted string inside comments. Once again, translators +should not burden themselves with quoting considerations besides, of +course, the necessity of the translated string itself respective to +the program using it. + +
++Note that k or w are not the only commands pushing strings +on the kill ring, as almost any PO mode command replacing translation +strings (or the translator comments) automatically save the old string +on the kill ring. The main exceptions to this general rule are the +yanking commands themselves. + +
+
+To better illustrate the operation of killing and yanking, let's
+use an actual example, taken from a common situation. When the
+programmer slightly modifies some string right in the program, his
+change is later reflected in the PO file by the appearance
+of a new untranslated entry for the modified string, and the fact
+that the entry translating the original or unmodified string becomes
+obsolete. In many cases, the translator might spare herself some work
+by retrieving the unmodified translation from the obsolete entry,
+then initializing the untranslated entry msgstr field with
+this retrieved translation. Once this done, the obsolete entry is
+not wanted anymore, and may be safely deleted.
+
+
+When the translator finds an untranslated entry and suspects that a
+slight variant of the translation exists, she immediately uses m
+to mark the current entry location, then starts chasing obsolete
+entries with o, hoping to find some translation corresponding
+to the unmodified string. Once found, she uses the DEL command
+for deleting the obsolete entry, knowing that DEL also kills
+the translation, that is, pushes the translation on the kill ring.
+Then, r returns to the initial untranslated entry, y
+then yanks the saved translation right into the msgstr
+field. The translator is then free to use RET for fine
+tuning the translation contents, and maybe to later use u,
+then m again, for going on with the next untranslated string.
+
+
+When some sequence of keys has to be typed over and over again, the +translator may find it useful to become better acquainted with the GNU +Emacs capability of learning these sequences and playing them back under +request. See section `Keyboard Macros' in The Emacs Editor. + +
+ + ++Any translation work done seriously will raise many linguistic +difficulties, for which decisions have to be made, and the choices +further documented. These documents may be saved within the +PO file in form of translator comments, which the translator +is free to create, delete, or modify at will. These comments may +be useful to herself when she returns to this PO file after a while. + +
+
+Comments not having whitespace after the initial `#', for example,
+those beginning with `#.' or `#:', are not translator
+comments, they are exclusively created by other gettext tools.
+So, the commands below will never alter such system added comments,
+they are not meant for the translator to modify. See section The Format of PO Files.
+
+
+The following commands are somewhat similar to those modifying translations, +so the general indications given for those apply here. See section Modifying Translations. + +
++These commands parallel PO mode commands for modifying the translation +strings, and behave much the same way as they do, except that they handle +this part of PO file comments meant for translator usage, rather +than the translation strings. So, if the descriptions given below are +slightly succinct, it is because the full details have already been given. +See section Modifying Translations. + +
+
+The command # (po-edit-comment) opens a new Emacs
+window containing a copy of the translator comments on the current
+PO file entry. If there are no such comments, PO mode
+understands that the translator wants to add a comment to the entry,
+and she is presented with an empty screen. Comment marks (#) and
+the space following them are automatically removed before edition,
+and reinstated after. For translator comments pertaining to obsolete
+entries, the uncommenting and recommenting operations are done twice.
+Once in the editing window, the keys C-c C-c allow the
+translator to tell she is finished with editing the comment.
+
+
+Functions found on po-subedit-mode-hook, if any, are executed after
+the string has been inserted in the edit buffer and before recursive edit
+is entered.
+
+
+The command K (po-kill-comment) get rid of all
+translator comments, while saving those comments on the kill ring.
+The command W (po-kill-ring-save-comment) takes
+a copy of the translator comments on the kill ring, but leaves
+them undisturbed in the current entry. The command Y
+(po-yank-comment) completely replaces the translator comments
+by a string taken at the front of the kill ring. When this command
+is immediately repeated, the comments just inserted are withdrawn,
+and replaced by other strings taken along the kill ring.
+
+
+On the kill ring, all strings have the same nature. There is no +distinction between translation strings and translator +comments strings. So, for example, let's presume the translator +has just finished editing a translation, and wants to create a new +translator comment to document why the previous translation was +not good, just to remember what was the problem. Foreseeing that she +will do that in her documentation, the translator may want to quote +the previous translation in her translator comments. To do so, she +may initialize the translator comments with the previous translation, +still at the head of the kill ring. Because editing already pushed the +previous translation on the kill ring, she merely has to type M-w +prior to #, and the previous translation will be right there, +all ready for being introduced by some explanatory text. + +
+
+On the other hand, presume there are some translator comments already
+and that the translator wants to add to those comments, instead
+of wholly replacing them. Then, she should edit the comment right
+away with #. Once inside the editing window, she can use the
+regular GNU Emacs commands C-y (yank) and M-y
+(yank-pop) to get the previous translation where she likes.
+
+
+PO mode is able to help the knowledgeable translator, being fluent in +many languages, at taking advantage of translations already achieved +in other languages she just happens to know. It provides these other +language translations as additional context for her own work. Moreover, +it has features to ease the production of translations for many languages +at once, for translators preferring to work in this way. + +
++An auxiliary PO file is an existing PO file meant for the same +package the translator is working on, but targeted to a different mother +tongue language. Commands exist for declaring and handling auxiliary +PO files, and also for showing contexts for the entry under work. + +
++Here are the auxiliary file commands available in PO mode. + +
+
+Command A (po-consider-as-auxiliary) adds the current
+PO file to the list of auxiliary files, while command M-A
+(po-ignore-as-auxiliary just removes it.
+
+
+The command a (po-cycle-auxiliary) seeks all auxiliary PO
+files, round-robin, searching for a translated entry in some other language
+having an msgid field identical as the one for the current entry.
+The found PO file, if any, takes the place of the current PO file in
+the display (its window gets on top). Before doing so, the current PO
+file is also made into an auxiliary file, if not already. So, a
+in this newly displayed PO file will seek another PO file, and so on,
+so repeating a will eventually yield back the original PO file.
+
+
+The command M-a (po-select-auxiliary) asks the translator
+for her choice of a particular auxiliary file, with completion, and
+then switches to that selected PO file. The command also checks if
+the selected file has an msgid field identical as the one for
+the current entry, and if yes, this entry becomes current. Otherwise,
+the cursor of the selected file is left undisturbed.
+
+
+For all this to work fully, auxiliary PO files will have to be normalized,
+in that way that msgid fields should be written exactly
+the same way. It is possible to write msgid fields in various
+ways for representing the same string, different writing would break the
+proper behaviour of the auxiliary file commands of PO mode. This is not
+expected to be much a problem in practice, as most existing PO files have
+their msgid entries written by the same GNU gettext tools.
+
+
+However, PO files initially created by PO mode itself, while marking
+strings in source files, are normalised differently. So are PO
+files resulting of the the `M-x normalize' command. Until these
+discrepancies between PO mode and other GNU gettext tools get
+fully resolved, the translator should stay aware of normalisation issues.
+
+
+
Go to the first, previous, next, last section, table of contents. + +