diff options
| author | Bruno Haible <bruno@clisp.org> | 2001-04-19 18:37:49 +0000 |
|---|---|---|
| committer | Bruno Haible <bruno@clisp.org> | 2001-04-19 18:37:49 +0000 |
| commit | 41ae7394123b8b0b13eb37ff1e9ed325374bbeba (patch) | |
| tree | 264af71280c09f69da43c6ad6ced7ba6633af09d /doc/gettext_6.html | |
| parent | 6ae7c1b1ba9f4f3aa1d78f121bc7ded6692d5f46 (diff) | |
| download | external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.zip external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.tar.gz external_gettext-41ae7394123b8b0b13eb37ff1e9ed325374bbeba.tar.bz2 | |
Automatically generated from gettext.texi.
Diffstat (limited to 'doc/gettext_6.html')
| -rw-r--r-- | doc/gettext_6.html | 930 |
1 files changed, 930 insertions, 0 deletions
diff --git a/doc/gettext_6.html b/doc/gettext_6.html new file mode 100644 index 0000000..363d567 --- /dev/null +++ b/doc/gettext_6.html @@ -0,0 +1,930 @@ +<HTML> +<HEAD> +<!-- This HTML file has been created by texi2html 1.51 + from gettext.texi on 19 April 2001 --> + +<TITLE>GNU gettext utilities - 6 Updating Existing PO Files</TITLE> +</HEAD> +<BODY> +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_5.html">previous</A>, <A HREF="gettext_7.html">next</A>, <A HREF="gettext_14.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +<P><HR><P> + + +<H1><A NAME="SEC22" HREF="gettext_toc.html#TOC22">6 Updating Existing PO Files</A></H1> + + + +<H2><A NAME="SEC23" HREF="gettext_toc.html#TOC23">6.1 Invoking the <CODE>msgmerge</CODE> Program</A></H2> + + + +<H2><A NAME="SEC24" HREF="gettext_toc.html#TOC24">6.2 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_6.html#SEC25">6.3 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_6.html#SEC28">6.6 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_6.html#SEC25">6.3 Fuzzy Entries</A>. + +</P> + + +<H2><A NAME="SEC25" HREF="gettext_toc.html#TOC25">6.3 Fuzzy Entries</A></H2> + +<P> +Each PO file entry may have a set of <STRONG>attributes</STRONG>, which are +qualities given a name and explicitely associated with the 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><KBD>TAB</KBD></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><KBD>TAB</KBD></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><KBD>TAB</KBD></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><KBD>RET</KBD></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><KBD>TAB</KBD></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><KBD>SPC</KBD></KBD> +to chase another entry, leaving the entry fuzzy. + +</P> +<P> +The translator may also use the <KBD><KBD>DEL</KBD></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="SEC26" HREF="gettext_toc.html#TOC26">6.4 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 for 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_6.html#SEC28">6.6 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="SEC27" HREF="gettext_toc.html#TOC27">6.5 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><KBD>DEL</KBD></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><KBD>DEL</KBD></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_6.html#SEC28">6.6 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="SEC28" HREF="gettext_toc.html#TOC28">6.6 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><KBD>RET</KBD></KBD> +<DD> +Interactively edit the translation. + +<DT><KBD><KBD>LFD</KBD></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><KBD>RET</KBD></KBD> (<CODE>po-edit-msgstr</CODE>) opens a new Emacs +window meant to edit in a new translation, or to modify an already existing +translation. The new window contains a copy of the translation taken from +the current PO file entry, all ready for edition, expunged of all quoting +marks, fully modifiable and with the complete extent of Emacs modifying +commands. When the translator is done with her modifications, she may use +<KBD>C-c C-c</KBD> to close the subedit window with the automatically requoted +results, or <KBD>C-c C-k</KBD> to abort her modifications. See section <A HREF="gettext_6.html#SEC30">6.8 Details of Sub Edition</A>, +for more information. + +</P> +<P> +The command <KBD><KBD>LFD</KBD></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><KBD>LFD</KBD></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 exists 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 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-line +strings are concatenated, and backslash 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 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 saves 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><KBD>DEL</KBD></KBD> command +for deleting the obsolete entry, knowing that <KBD><KBD>DEL</KBD></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, and <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 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="SEC29" HREF="gettext_toc.html#TOC29">6.7 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">2.2 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_6.html#SEC28">6.6 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_6.html#SEC28">6.6 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. +See section <A HREF="gettext_6.html#SEC30">6.8 Details of Sub Edition</A>, for further details. + +</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. + +</P> +<P> +The command <KBD>K</KBD> (<CODE>po-kill-comment</CODE>) gets 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 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="SEC30" HREF="gettext_toc.html#TOC30">6.8 Details of Sub Edition</A></H2> + +<P> +The PO subedit minor mode has a few peculiarities worth being described +in fuller detail. It installs a few commands over the usual editing set +of Emacs, which are described below. + +</P> +<DL COMPACT> + +<DT><KBD>C-c C-c</KBD> +<DD> +Complete edition. + +<DT><KBD>C-c C-k</KBD> +<DD> +Abort edition. + +<DT><KBD>C-c C-a</KBD> +<DD> +Consult auxiliary PO files. + +</DL> + +<P> +The window's contents represents a translation for a given message, +or a translator comment. The translator may modify this window to +her heart's content. Once this done, the command <KBD>C-c C-c</KBD> +(<CODE>po-subedit-exit</CODE>) may be used to return the edited translation into +the PO file, replacing the original translation, even if it moved out of +sight or if buffers were switched. + +</P> +<P> +If the translator becomes unsatisfied with her translation or comment, +to the extent she prefers keeping what was existent prior to the +<KBD><KBD>RET</KBD></KBD> or <KBD>#</KBD> command, she may use the command <KBD>C-c C-k</KBD> +(<CODE>po-subedit-abort</CODE>) to merely get rid of edition, while preserving +the original translation or comment. 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> +The command <KBD>C-c C-a</KBD> allows for glancing through translations +already achieved in other languages, directly while editing the current +translation. This may be quite convenient when the translator is fluent +at many languages, but of course, only makes sense when such completed +auxiliary PO files are already available to her (see section <A HREF="gettext_6.html#SEC32">6.10 Consulting Auxiliary PO Files</A>). + +</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. + +</P> +<P> +While editing her translation, the translator should pay attention to not +inserting unwanted <KBD><KBD>RET</KBD></KBD> (newline) 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><</KBD> +at the end of the string being edited, but this <KBD><</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><</KBD> and all whitespace added after +it. If the translator adds characters after the terminating <KBD><</KBD>, it +looses its delimiting property and integrally becomes part of the string. +If she removes the delimiting <KBD><</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><</KBD>, then +the delimiting <KBD><</KBD> may not be removed; so the string should appear, +in the editing window, as ending with two <KBD><</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. If, with an edition pending, the translator wanders in the +PO file buffer, she may decide to start modifying another entry. Each entry +being edited has its own subedit buffer. It is possible to simultaneously +edit the translation <EM>and</EM> the comment of a single entry, or to +edit entries in different PO files, all at once. Typing <KBD><KBD>RET</KBD></KBD> +on a field already being edited merely resumes that particular edit. Yet, +the translator should better be comfortable at handling many Emacs windows! + +</P> +<P> +Pending subedits may be completed or aborted in any order, regardless +of how or when they were started. When many subedits are pending and the +translator asks for quitting the PO file (with the <KBD>q</KBD> command), subedits +are automatically resumed one at a time, so she may decide for each of them. + +</P> + + +<H2><A NAME="SEC31" HREF="gettext_toc.html#TOC31">6.9 C Sources Context</A></H2> + +<P> +PO mode is particularily powerful when used with PO files +created through GNU <CODE>gettext</CODE> utilities, as those utilities +insert special comments in the PO files they generate. +Some of these special comments relate the PO file entry to +exactly where the untranslated string appears in the program sources. + +</P> +<P> +When the translator gets to an untranslated entry, she is fairly +often faced with an original string which is not as informative as +it normally should be, being succinct, cryptic, or otherwise ambiguous. +Before chosing how to translate the string, she needs to understand +better what the string really means and how tight the translation has +to be. Most of times, when problems arise, the only way left to make +her judgment is looking at the true program sources from where this +string originated, searching for surrounding comments the programmer +might have put in there, and looking around for helping clues of +<EM>any</EM> kind. + +</P> +<P> +Surely, when looking at program sources, the translator will receive +more help if she is a fluent programmer. However, even if she is +not versed in programming and feels a little lost in C code, the +translator should not be shy at taking a look, once in a while. +It is most probable that she will still be able to find some of the +hints she needs. She will learn quickly to not feel uncomfortable +in program code, paying more attention to programmer's comments, +variable and function names (if he dared chosing them well), and +overall organization, than to programmation itself. + +</P> +<P> +The following commands are meant to help the translator at getting +program source context for a PO file entry. + +</P> +<DL COMPACT> + +<DT><KBD>s</KBD> +<DD> +Resume the display of a program source context, or cycle through them. + +<DT><KBD>M-s</KBD> +<DD> +Display of a program source context selected by menu. + +<DT><KBD>S</KBD> +<DD> +Add a directory to the search path for source files. + +<DT><KBD>M-S</KBD> +<DD> +Delete a directory from the search path for source files. + +</DL> + +<P> +The commands <KBD>s</KBD> (<CODE>po-cycle-reference</CODE>) and <KBD>M-s</KBD> +(<CODE>po-select-source-reference</CODE>) both open another window displaying +some source program file, and already positioned in such a way that +it shows an actual use of the string to be translated. By doing +so, the command gives source program context for the string. But if +the entry has no source context references, or if all references +are unresolved along the search path for program sources, then the +command diagnoses this as an error. + +</P> +<P> +Even if <KBD>s</KBD> (or <KBD>M-s</KBD>) opens a new window, the cursor stays +in the PO file window. If the translator really wants to +get into the program source window, she ought to do it explicitly, +maybe by using command <KBD>O</KBD>. + +</P> +<P> +When <KBD>s</KBD> is typed for the first time, or for a PO file entry which +is different of the last one used for getting source context, then the +command reacts by giving the first context available for this entry, +if any. If some context has already been recently displayed for the +current PO file entry, and the translator wandered off to do other +things, typing <KBD>s</KBD> again will merely resume, in another window, +the context last displayed. In particular, if the translator moved +the cursor away from the context in the source file, the command will +bring the cursor back to the context. By using <KBD>s</KBD> many times +in a row, with no other commands intervening, PO mode will cycle to +the next available contexts for this particular entry, getting back +to the first context once the last has been shown. + +</P> +<P> +The command <KBD>M-s</KBD> behaves differently. Instead of cycling through +references, it lets the translator choose a particular reference among +many, and displays that reference. It is best used with completion, +if the translator types <KBD><KBD>TAB</KBD></KBD> immediately after <KBD>M-s</KBD>, in +response to the question, she will be offered a menu of all possible +references, as a reminder of which are the acceptable answers. +This command is useful only where there are really many contexts +available for a single string to translate. + +</P> +<P> +Program source files are usually found relative to where the PO +file stands. As a special provision, when this fails, the file is +also looked for, but relative to the directory immediately above it. +Those two cases take proper care of most PO files. However, it might +happen that a PO file has been moved, or is edited in a different +place than its normal location. When this happens, the translator +should tell PO mode in which directory normally sits the genuine PO +file. Many such directories may be specified, and all together, they +constitute what is called the <STRONG>search path</STRONG> for program sources. +The command <KBD>S</KBD> (<CODE>po-consider-source-path</CODE>) is used to interactively +enter a new directory at the front of the search path, and the command +<KBD>M-S</KBD> (<CODE>po-ignore-source-path</CODE>) is used to select, with completion, +one of the directories she does not want anymore on the search path. + +</P> + + +<H2><A NAME="SEC32" HREF="gettext_toc.html#TOC32">6.10 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> + + +<H2><A NAME="SEC33" HREF="gettext_toc.html#TOC33">6.11 Using Translation Compendiums</A></H2> + +<P> +Compendiums are yet to be implemented. + +</P> +<P> +An incoming PO mode feature will let the translator maintain a +compendium of already achieved translations. A <STRONG>compendium</STRONG> +is a special PO file containing a set of translations recurring in +many different packages. The translator will be given commands for +adding entries to her compendium, and later initializing untranslated +entries, or updating already translated entries, from translations +kept in the compendium. For this to work, however, the compendium +would have to be normalized. See section <A HREF="gettext_2.html#SEC12">2.5 Normalizing Strings in Entries</A>. + +</P> + +<P><HR><P> +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_5.html">previous</A>, <A HREF="gettext_7.html">next</A>, <A HREF="gettext_14.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +</BODY> +</HTML> |