X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7921cf2badfac0c44cd53644bfc6a483a09ec299..93c4157c6cf8603eaba7ebbbc3b1e7bd303d8241:/docs/html/gettext/gettext_5.html

diff --git a/docs/html/gettext/gettext_5.html b/docs/html/gettext/gettext_5.html
new file mode 100644
index 0000000000..81f4c9a24b
--- /dev/null
+++ b/docs/html/gettext/gettext_5.html
@@ -0,0 +1,747 @@
+<HTML>
+<HEAD>
+<!-- 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>
+<link href="gettext_6.html" rel=Next>
+<link href="gettext_4.html" rel=Previous>
+<link href="gettext_toc.html" rel=ToC>
+
+</HEAD>
+<BODY>
+<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>.
+<P><HR><P>
+
+
+<H1><A NAME="SEC23" HREF="gettext_toc.html#TOC23">Updating Existing PO Files</A></H1>
+
+
+
+<H2><A NAME="SEC24" HREF="gettext_toc.html#TOC24">Invoking the <CODE>msgmerge</CODE> Program</A></H2>
+
+
+
+<H2><A NAME="SEC25" HREF="gettext_toc.html#TOC25">Translated Entries</A></H2>
+
+<P>
+Each PO file entry for which the <CODE>msgstr</CODE> field has been filled with
+a translation, and which is not marked as fuzzy (see section <A HREF="gettext_5.html#SEC26">Fuzzy Entries</A>),
+is a said to be a <STRONG>translated</STRONG> entry.  Only translated entries will
+later be compiled by GNU <CODE>msgfmt</CODE> and become usable in programs.
+Other entry types will be excluded; translation will not occur for them.
+
+</P>
+<P>
+Some commands are more specifically related to translated entry processing.
+
+</P>
+<DL COMPACT>
+
+<DT><KBD>t</KBD>
+<DD>
+Find the next translated entry.
+
+<DT><KBD>M-t</KBD>
+<DD>
+Find the previous translated entry.
+
+</DL>
+
+<P>
+The commands <KBD>t</KBD> (<CODE>po-next-translated-entry</CODE>) and <KBD>M-t</KBD>
+(<CODE>po-previous-transted-entry</CODE>) 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.
+
+</P>
+<P>
+Translated entries usually result from the translator having edited in
+a translation for them, section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>.  However, if the
+variable <CODE>po-auto-fuzzy-on-edit</CODE> is not <CODE>nil</CODE>, 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 <A HREF="gettext_5.html#SEC26">Fuzzy Entries</A>.
+
+</P>
+
+
+<H2><A NAME="SEC26" HREF="gettext_toc.html#TOC26">Fuzzy Entries</A></H2>
+
+<P>
+Each PO file entry may have a set of <STRONG>attributes</STRONG>, which are
+qualities given an name and explicitely associated with the entry
+translation, using a special system comment.  One of these attributes
+has the name <CODE>fuzzy</CODE>, and entries having this attribute are said
+to have a fuzzy translation.  They are called fuzzy entries, for short.
+
+</P>
+<P>
+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 <CODE>msgmerge</CODE> to
+update an older translated PO files according to a new PO template
+file, when this tool hypothesises that some new <CODE>msgid</CODE> 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 <CODE>msgid</CODE> string)
+should often be reflected in the translated string, and this requires
+the intervention of the translator.  For this reason, <CODE>msgmerge</CODE>
+might mark some entries as being fuzzy.
+
+</P>
+<P>
+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.
+
+</P>
+<DL COMPACT>
+
+<DT><KBD>f</KBD>
+<DD>
+Find the next fuzzy entry.
+
+<DT><KBD>M-f</KBD>
+<DD>
+Find the previous fuzzy entry.
+
+<DT><KBD>TAB</KBD>
+<DD>
+Remove the fuzzy attribute of the current entry.
+
+</DL>
+
+<P>
+The commands <KBD>f</KBD> (<CODE>po-next-fuzzy</CODE>) and <KBD>M-f</KBD>
+(<CODE>po-previous-fuzzy</CODE>) 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.
+
+</P>
+<P>
+The command <KBD>TAB</KBD> (<CODE>po-unfuzzy</CODE>) removes the fuzzy
+attribute associated with an entry, usually leaving it translated.
+Further, if the variable <CODE>po-auto-select-on-unfuzzy</CODE> has not
+the <CODE>nil</CODE> value, the <KBD>TAB</KBD> command will automatically chase
+for another interesting entry to work on.  The initial value of
+<CODE>po-auto-select-on-unfuzzy</CODE> is <CODE>nil</CODE>.
+
+</P>
+<P>
+The initial value of <CODE>po-auto-fuzzy-on-edit</CODE> is <CODE>nil</CODE>.  However,
+if the variable <CODE>po-auto-fuzzy-on-edit</CODE> is set to <CODE>t</CODE>, any entry
+edited through the <KBD>RET</KBD> 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
+<KBD>TAB</KBD> to pick another entry to work on, clearing the fuzzy attribute
+on the same blow.  If she is not satisfied yet, she merely uses <KBD>SPC</KBD>
+to chase another entry, leaving the entry fuzzy.
+
+</P>
+<P>
+The translator may also use the <KBD>DEL</KBD> command
+(<CODE>po-fade-out-entry</CODE>) 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.
+
+</P>
+<P>
+Also, when time comes to quit working on a PO file buffer with the <KBD>q</KBD>
+command, the translator is asked for confirmation, if fuzzy string
+still exists.
+
+</P>
+
+
+<H2><A NAME="SEC27" HREF="gettext_toc.html#TOC27">Untranslated Entries</A></H2>
+
+<P>
+When <CODE>xgettext</CODE> originally creates a PO file, unless told
+otherwise, it initializes the <CODE>msgid</CODE> field with the untranslated
+string, and leaves the <CODE>msgstr</CODE> string to be empty.  Such entries,
+having an empty translation, are said to be <STRONG>untranslated</STRONG> 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.
+
+</P>
+<P>
+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 <SAMP>`msgstr ""'</SAMP>.
+
+</P>
+<P>
+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.
+
+</P>
+<DL COMPACT>
+
+<DT><KBD>u</KBD>
+<DD>
+Find the next untranslated entry.
+
+<DT><KBD>M-u</KBD>
+<DD>
+Find the previous untranslated entry.
+
+<DT><KBD>k</KBD>
+<DD>
+Turn the current entry into an untranslated one.
+
+</DL>
+
+<P>
+The commands <KBD>u</KBD> (<CODE>po-next-untranslated-entry</CODE>) and <KBD>M-u</KBD>
+(<CODE>po-previous-untransted-entry</CODE>) 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.
+
+</P>
+<P>
+An entry can be turned back into an untranslated entry by
+merely emptying its translation, using the command <KBD>k</KBD>
+(<CODE>po-kill-msgstr</CODE>).  See section <A HREF="gettext_5.html#SEC29">Modifying Translations</A>.
+
+</P>
+<P>
+Also, when time comes to quit working on a PO file buffer
+with the <KBD>q</KBD> command, the translator is asked for confirmation,
+if some untranslated string still exists.
+
+</P>
+
+
+<H2><A NAME="SEC28" HREF="gettext_toc.html#TOC28">Obsolete Entries</A></H2>
+
+<P>
+By <STRONG>obsolete</STRONG> PO file entries, we mean those entries which are
+commented out, usually by <CODE>msgmerge</CODE> when it found that the
+translation is not needed anymore by the package being localized.
+
+</P>
+<P>
+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
+<KBD>#</KBD>, even those lines containing <CODE>msgid</CODE> or <CODE>msgstr</CODE>.
+
+</P>
+<P>
+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.
+
+</P>
+<P>
+Moreover, some commands are more specifically related to obsolete
+entry processing.
+
+</P>
+<DL COMPACT>
+
+<DT><KBD>o</KBD>
+<DD>
+Find the next obsolete entry.
+
+<DT><KBD>M-o</KBD>
+<DD>
+Find the previous obsolete entry.
+
+<DT><KBD>DEL</KBD>
+<DD>
+Make an active entry obsolete, or zap out an obsolete entry.
+
+</DL>
+
+<P>
+The commands <KBD>o</KBD> (<CODE>po-next-obsolete-entry</CODE>) and <KBD>M-o</KBD>
+(<CODE>po-previous-obsolete-entry</CODE>) 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.
+
+</P>
+<P>
+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 <CODE>msgid</CODE> values.
+
+</P>
+<P>
+However, it is possible to comment out an active entry, so making
+it obsolete.  GNU <CODE>gettext</CODE> utilities will later react to the
+disappearance of a translation by using the untranslated string.
+The command <KBD>DEL</KBD> (<CODE>po-fade-out-entry</CODE>) 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 <A HREF="gettext_5.html#SEC29">Modifying Translations</A>.
+
+</P>
+<P>
+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.
+
+</P>
+
+
+<H2><A NAME="SEC29" HREF="gettext_toc.html#TOC29">Modifying Translations</A></H2>
+
+<P>
+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
+<KBD>V</KBD> 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.
+
+</P>
+<P>
+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.
+
+</P>
+<DL COMPACT>
+
+<DT><KBD>RET</KBD>
+<DD>
+Interactively edit the translation.
+
+<DT><KBD>LFD</KBD>
+<DD>
+Reinitialize the translation with the original, untranslated string.
+
+<DT><KBD>k</KBD>
+<DD>
+Save the translation on the kill ring, and delete it.
+
+<DT><KBD>w</KBD>
+<DD>
+Save the translation on the kill ring, without deleting it.
+
+<DT><KBD>y</KBD>
+<DD>
+Replace the translation, taking the new from the kill ring.
+
+</DL>
+
+<P>
+The command <KBD>RET</KBD> (<CODE>po-edit-msgstr</CODE>) 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 <EM>unquoted</EM>
+string in this window to heart's content.  Once done, the regular Emacs
+command <KBD>M-C-c</KBD> (<CODE>exit-recursive-edit</CODE>) may be used to return the
+edited translation into the PO file, replacing the original translation.
+The keys <KBD>C-c C-c</KBD> are bound so they have the same effect as
+<KBD>M-C-c</KBD>.
+
+</P>
+<P>
+If the translator becomes unsatisfied with her translation to the extent
+she prefers keeping the translation which was existent prior to the
+<KBD>RET</KBD> command, she may use the standard Emacs command <KBD>C-]</KBD>
+(<CODE>abort-recursive-edit</CODE>) to merely get rid of edition, while
+preserving the original translation.  The keys <KBD>C-c C-k</KBD> are
+bound so they have the same effect as <KBD>C-]</KBD>.  Another way would
+be for her to exit normally with <KBD>C-c C-c</KBD>, then type <CODE>U</CODE>
+once for undoing the whole effect of last edition.
+
+</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>
+While editing her translation, the translator should pay attention to
+not inserting unwanted <KBD><KBD>RET</KBD></KBD> (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, <KBD><KBD>RET</KBD></KBD> automatically puts
+the character <KBD>&#60;</KBD> at the end of the string being edited, but this
+<KBD>&#60;</KBD> is not really part of the string.  On exiting the editing
+window with <KBD>C-c C-c</KBD>, PO mode automatically removes such
+<KBD>&#60;</KBD> and all whitespace added after it.  If the translator adds
+characters after the terminating <KBD>&#60;</KBD>, it looses its delimiting
+property and integrally becomes part of the string.  If she removes
+the delimiting <KBD>&#60;</KBD>, then the edited string is taken <EM>as
+is</EM>, with all trailing newlines, even if invisible.  Also, if the
+translated string ought to end itself with a genuine <KBD>&#60;</KBD>, then the
+delimiting <KBD>&#60;</KBD> may not be removed; so the string should appear,
+in the editing window, as ending with two <KBD>&#60;</KBD> in a row.
+
+</P>
+<P>
+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.
+
+</P>
+<P>
+The command <KBD>LFD</KBD> (<CODE>po-msgid-to-msgstr</CODE>) 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.
+
+</P>
+<P>
+It is possible to arrange so, whenever editing an untranslated
+entry, the <KBD>LFD</KBD> command be automatically executed.  If you set
+<CODE>po-auto-edit-with-msgid</CODE> to <CODE>t</CODE>, the translation gets
+initialised with the original string, in case none exist already.
+The default value for <CODE>po-auto-edit-with-msgid</CODE> is <CODE>nil</CODE>.
+
+</P>
+<P>
+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.
+
+</P>
+<P>
+The command <KBD>k</KBD> (<CODE>po-kill-msgstr</CODE>) 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 <KBD>w</KBD>
+(<CODE>po-kill-ring-save-msgstr</CODE>) has also the effect of taking a
+copy of the translation onto the kill ring, but it otherwise leaves
+the entry alone, and does <EM>not</EM> 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.
+
+</P>
+<P>
+The translator may use <KBD>k</KBD> or <KBD>w</KBD> 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.
+
+</P>
+<P>
+To facilitate exchanges with buffers which are not in PO mode, the
+translation string put on the kill ring by the <KBD>k</KBD> 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.
+
+</P>
+<P>
+The command <KBD>y</KBD> (<CODE>po-yank-msgstr</CODE>) 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 <STRONG>yanked</STRONG> into the PO file buffer.
+See section `Yanking' in <CITE>The Emacs Editor</CITE>.
+The first time <KBD>y</KBD> is used, the translation receives the value of
+the most recent addition to the kill ring.  If <KBD>y</KBD> 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 <KBD>y</KBD> many times in a row,
+the translator may travel along the kill ring for saved strings,
+until she finds the string she really wanted.
+
+</P>
+<P>
+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.
+
+</P>
+<P>
+Note that <KBD>k</KBD> or <KBD>w</KBD> 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.
+
+</P>
+<P>
+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 <CODE>msgstr</CODE> field with
+this retrieved translation.  Once this done, the obsolete entry is
+not wanted anymore, and may be safely deleted.
+
+</P>
+<P>
+When the translator finds an untranslated entry and suspects that a
+slight variant of the translation exists, she immediately uses <KBD>m</KBD>
+to mark the current entry location, then starts chasing obsolete
+entries with <KBD>o</KBD>, hoping to find some translation corresponding
+to the unmodified string.  Once found, she uses the <KBD>DEL</KBD> command
+for deleting the obsolete entry, knowing that <KBD>DEL</KBD> also <EM>kills</EM>
+the translation, that is, pushes the translation on the kill ring.
+Then, <KBD>r</KBD> returns to the initial untranslated entry, <KBD>y</KBD>
+then <EM>yanks</EM> the saved translation right into the <CODE>msgstr</CODE>
+field.  The translator is then free to use <KBD><KBD>RET</KBD></KBD> for fine
+tuning the translation contents, and maybe to later use <KBD>u</KBD>,
+then <KBD>m</KBD> again, for going on with the next untranslated string.
+
+</P>
+<P>
+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 <CITE>The Emacs Editor</CITE>.
+
+</P>
+
+
+<H2><A NAME="SEC30" HREF="gettext_toc.html#TOC30">Modifying Comments</A></H2>
+
+<P>
+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 <A HREF="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 <A HREF="gettext_5.html#SEC29">Modifying Translations</A>.
+
+</P>
+<DL COMPACT>
+
+<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 <A HREF="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><A NAME="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>
+<DL COMPACT>
+
+<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 <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>.
+</BODY>
+</HTML>