gettext: Modifying Translations

1 
1 8.3.9 Modifying Translations
1 ----------------------------
1 
1    PO mode prevents direct modification of the PO file, by the usual
1 means Emacs gives for altering a buffer’s contents.  By doing so, it
1 pretends helping the translator to avoid little clerical errors about
1 the overall file format, or the proper quoting of strings, as those
1 errors would be easily made.  Other kinds of errors are still possible,
1 but some may be caught and diagnosed by the batch validation process,
1 which the translator may always trigger by the ‘V’ command.  For all
1 other errors, the translator has to rely on her own judgment, and also
1 on the linguistic reports submitted to her by the users of the
1 translated package, having the same mother tongue.
1 
1    When the time comes to create a translation, correct an error
1 diagnosed mechanically or reported by a user, the translators have to
1 resort to using the following commands for modifying the translations.
1 
1 ‘<RET>’
1      Interactively edit the translation (‘po-edit-msgstr’).
1 
1 ‘<LFD>’
1 ‘C-j’
1      Reinitialize the translation with the original, untranslated string
1      (‘po-msgid-to-msgstr’).
1 
1 ‘k’
1      Save the translation on the kill ring, and delete it
1      (‘po-kill-msgstr’).
1 
1 ‘w’
1      Save the translation on the kill ring, without deleting it
1      (‘po-kill-ring-save-msgstr’).
1 
1 ‘y’
1      Replace the translation, taking the new from the kill ring
1      (‘po-yank-msgstr’).
1 
1    The command ‘<RET>’ (‘po-edit-msgstr’) opens a new Emacs window meant
1 to edit in a new translation, or to modify an already existing
1 translation.  The new window contains a copy of the translation taken
1 from the current PO file entry, all ready for edition, expunged of all
1 quoting marks, fully modifiable and with the complete extent of Emacs
1 modifying commands.  When the translator is done with her modifications,
1 she may use ‘C-c C-c’ to close the subedit window with the automatically
11 requoted results, or ‘C-c C-k’ to abort her modifications.  ⇒
 Subedit, for more information.
1 
1    The command ‘<LFD>’ (‘po-msgid-to-msgstr’) initializes, or
1 reinitializes the translation with the original string.  This command is
1 normally used when the translator wants to redo a fresh translation of
1 the original string, disregarding any previous work.
1 
1    It is possible to arrange so, whenever editing an untranslated entry,
1 the ‘<LFD>’ command be automatically executed.  If you set
1 ‘po-auto-edit-with-msgid’ to ‘t’, the translation gets initialised with
1 the original string, in case none exists already.  The default value for
1 ‘po-auto-edit-with-msgid’ is ‘nil’.
1 
1    In fact, whether it is best to start a translation with an empty
1 string, or rather with a copy of the original string, is a matter of
1 taste or habit.  Sometimes, the source language and the target language
1 are so different that is simply best to start writing on an empty page.
1 At other times, the source and target languages are so close that it
1 would be a waste to retype a number of words already being written in
1 the original string.  A translator may also like having the original
1 string right under her eyes, as she will progressively overwrite the
1 original text with the translation, even if this requires some extra
1 editing work to get rid of the original.
1 
1    The command ‘k’ (‘po-kill-msgstr’) merely empties the translation
1 string, so turning the entry into an untranslated one.  But while doing
1 so, its previous contents is put apart in a special place, known as the
1 kill ring.  The command ‘w’ (‘po-kill-ring-save-msgstr’) has also the
1 effect of taking a copy of the translation onto the kill ring, but it
1 otherwise leaves the entry alone, and does _not_ remove the translation
1 from the entry.  Both commands use exactly the Emacs kill ring, which is
1 shared between buffers, and which is well known already to Emacs lovers.
1 
1    The translator may use ‘k’ or ‘w’ many times in the course of her
1 work, as the kill ring may hold several saved translations.  From the
1 kill ring, strings may later be reinserted in various Emacs buffers.  In
1 particular, the kill ring may be used for moving translation strings
1 between different entries of a single PO file buffer, or if the
1 translator is handling many such buffers at once, even between PO files.
1 
1    To facilitate exchanges with buffers which are not in PO mode, the
1 translation string put on the kill ring by the ‘k’ command is fully
1 unquoted before being saved: external quotes are removed, multi-line
1 strings are concatenated, and backslash escaped sequences are turned
1 into their corresponding characters.  In the special case of obsolete
1 entries, the translation is also uncommented prior to saving.
1 
1    The command ‘y’ (‘po-yank-msgstr’) completely replaces the
1 translation of the current entry by a string taken from the kill ring.
1 Following Emacs terminology, we then say that the replacement string is
1 "yanked" into the PO file buffer.  ⇒(emacs)Yanking.  The first
1 time ‘y’ is used, the translation receives the value of the most recent
1 addition to the kill ring.  If ‘y’ is typed once again, immediately,
1 without intervening keystrokes, the translation just inserted is taken
1 away and replaced by the second most recent addition to the kill ring.
1 By repeating ‘y’ many times in a row, the translator may travel along
1 the kill ring for saved strings, until she finds the string she really
1 wanted.
1 
1    When a string is yanked into a PO file entry, it is fully and
1 automatically requoted for complying with the format PO files should
1 have.  Further, if the entry is obsolete, PO mode then appropriately
1 push the inserted string inside comments.  Once again, translators
1 should not burden themselves with quoting considerations besides, of
1 course, the necessity of the translated string itself respective to the
1 program using it.
1 
1    Note that ‘k’ or ‘w’ are not the only commands pushing strings on the
1 kill ring, as almost any PO mode command replacing translation strings
1 (or the translator comments) automatically saves the old string on the
1 kill ring.  The main exceptions to this general rule are the yanking
1 commands themselves.
1 
1    To better illustrate the operation of killing and yanking, let’s use
1 an actual example, taken from a common situation.  When the programmer
1 slightly modifies some string right in the program, his change is later
1 reflected in the PO file by the appearance of a new untranslated entry
1 for the modified string, and the fact that the entry translating the
1 original or unmodified string becomes obsolete.  In many cases, the
1 translator might spare herself some work by retrieving the unmodified
1 translation from the obsolete entry, then initializing the untranslated
1 entry ‘msgstr’ field with this retrieved translation.  Once this done,
1 the obsolete entry is not wanted anymore, and may be safely deleted.
1 
1    When the translator finds an untranslated entry and suspects that a
1 slight variant of the translation exists, she immediately uses ‘m’ to
1 mark the current entry location, then starts chasing obsolete entries
1 with ‘o’, hoping to find some translation corresponding to the
1 unmodified string.  Once found, she uses the ‘<DEL>’ command for
1 deleting the obsolete entry, knowing that ‘<DEL>’ also _kills_ the
1 translation, that is, pushes the translation on the kill ring.  Then,
1 ‘r’ returns to the initial untranslated entry, and ‘y’ then _yanks_ the
1 saved translation right into the ‘msgstr’ field.  The translator is then
1 free to use ‘<RET>’ for fine tuning the translation contents, and maybe
1 to later use ‘u’, then ‘m’ again, for going on with the next
1 untranslated string.
1 
1    When some sequence of keys has to be typed over and over again, the
1 translator may find it useful to become better acquainted with the Emacs
1 capability of learning these sequences and playing them back under
1 request.  ⇒(emacs)Keyboard Macros.
1