<!-- This HTML file has been created by texi2html 1.54
from gettext.texi on 25 January 1999 -->
<TITLE>GNU gettext utilities - Updating Existing PO Files</TITLE>
<linkhref="gettext_6.html"rel=Next>
<linkhref="gettext_4.html"rel=Previous>
<linkhref="gettext_toc.html"rel=ToC>
</HEAD>
<BODY>
<p>Go to the <AHREF="gettext_1.html">first</A>, <AHREF="gettext_4.html">previous</A>, <AHREF="gettext_6.html">next</A>, <AHREF="gettext_12.html">last</A> section, <AHREF="gettext_toc.html">table of contents</A>.
<P><HR><P>
<H1><ANAME="SEC23"HREF="gettext_toc.html#TOC23">Updating Existing PO Files</A></H1>
<H2><ANAME="SEC24"HREF="gettext_toc.html#TOC24">Invoking the <CODE>msgmerge</CODE> Program</A></H2>
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.
</P>
<P>
Comments not having whitespace after the initial <SAMP>`#'</SAMP>, for example,
those beginning with <SAMP>`#.'</SAMP> or <SAMP>`#:'</SAMP>, are <EM>not</EM> translator
comments, they are exclusively created by other <CODE>gettext</CODE> tools.
So, the commands below will never alter such system added comments,
they are not meant for the translator to modify. See section <AHREF="gettext_2.html#SEC9">The Format of PO Files</A>.
</P>
<P>
The following commands are somewhat similar to those modifying translations,
so the general indications given for those apply here. See section <AHREF="gettext_5.html#SEC29">Modifying Translations</A>.
</P>
<DLCOMPACT>
<DT><KBD>#</KBD>
<DD>
Interactively edit the translator comments.
<DT><KBD>K</KBD>
<DD>
Save the translator comments on the kill ring, and delete it.
<DT><KBD>W</KBD>
<DD>
Save the translator comments on the kill ring, without deleting it.
<DT><KBD>Y</KBD>
<DD>
Replace the translator comments, taking the new from the kill ring.
</DL>
<P>
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 <AHREF="gettext_5.html#SEC29">Modifying Translations</A>.
</P>
<P>
The command <KBD>#</KBD> (<CODE>po-edit-comment</CODE>) 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 (<KBD>#</KBD>) 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 <KBD>C-c C-c</KBD> allow the
translator to tell she is finished with editing the comment.
</P>
<P>
Functions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after
the string has been inserted in the edit buffer and before recursive edit
is entered.
</P>
<P>
The command <KBD>K</KBD> (<CODE>po-kill-comment</CODE>) get rid of all
translator comments, while saving those comments on the kill ring.
The command <KBD>W</KBD> (<CODE>po-kill-ring-save-comment</CODE>) takes
a copy of the translator comments on the kill ring, but leaves
them undisturbed in the current entry. The command <KBD>Y</KBD>
(<CODE>po-yank-comment</CODE>) 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.
</P>
<P>
On the kill ring, all strings have the same nature. There is no
distinction between <EM>translation</EM> strings and <EM>translator
comments</EM> 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 <KBD>M-w</KBD>
prior to <KBD>#</KBD>, and the previous translation will be right there,
all ready for being introduced by some explanatory text.
</P>
<P>
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 <KBD>#</KBD>. Once inside the editing window, she can use the
regular GNU Emacs commands <KBD>C-y</KBD> (<CODE>yank</CODE>) and <KBD>M-y</KBD>
(<CODE>yank-pop</CODE>) to get the previous translation where she likes.
</P>
<H2><ANAME="SEC31"HREF="gettext_toc.html#TOC31">Consulting Auxiliary PO Files</A></H2>
<P>
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.
</P>
<P>
An <STRONG>auxiliary</STRONG> 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.
</P>
<P>
Here are the auxiliary file commands available in PO mode.
</P>
<DLCOMPACT>
<DT><KBD>a</KBD>
<DD>
Seek auxiliary files for another translation for the same entry.
<DT><KBD>M-a</KBD>
<DD>
Switch to a particular auxiliary file.
<DT><KBD>A</KBD>
<DD>
Declare this PO file as an auxiliary file.
<DT><KBD>M-A</KBD>
<DD>
Remove this PO file from the list of auxiliary files.
</DL>
<P>
Command <KBD>A</KBD> (<CODE>po-consider-as-auxiliary</CODE>) adds the current
PO file to the list of auxiliary files, while command <KBD>M-A</KBD>
(<CODE>po-ignore-as-auxiliary</CODE> just removes it.
</P>
<P>
The command <KBD>a</KBD> (<CODE>po-cycle-auxiliary</CODE>) seeks all auxiliary PO
files, round-robin, searching for a translated entry in some other language
having an <CODE>msgid</CODE> 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, <KBD>a</KBD>
in this newly displayed PO file will seek another PO file, and so on,
so repeating <KBD>a</KBD> will eventually yield back the original PO file.
</P>
<P>
The command <KBD>M-a</KBD> (<CODE>po-select-auxiliary</CODE>) 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 <CODE>msgid</CODE> 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.
</P>
<P>
For all this to work fully, auxiliary PO files will have to be normalized,
in that way that <CODE>msgid</CODE> fields should be written <EM>exactly</EM>
the same way. It is possible to write <CODE>msgid</CODE> 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 <CODE>msgid</CODE> entries written by the same GNU <CODE>gettext</CODE> tools.
</P>
<P>
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 <SAMP>`M-x normalize'</SAMP> command. Until these
discrepancies between PO mode and other GNU <CODE>gettext</CODE> tools get
fully resolved, the translator should stay aware of normalisation issues.
</P>
<P><HR><P>
<p>Go to the <AHREF="gettext_1.html">first</A>, <AHREF="gettext_4.html">previous</A>, <AHREF="gettext_6.html">next</A>, <AHREF="gettext_12.html">last</A> section, <AHREF="gettext_toc.html">table of contents</A>.
