X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fc2171bd4c660b8554dae2a1cbf34ff09f3032a6..c8c77ee2af68bcea8ba157b4d5a4e2cd5b4912bd:/docs/html/gettext/gettext_5.html diff --git a/docs/html/gettext/gettext_5.html b/docs/html/gettext/gettext_5.html deleted file mode 100644 index 9617b66bf8..0000000000 --- a/docs/html/gettext/gettext_5.html +++ /dev/null @@ -1,747 +0,0 @@ - - - - -GNU gettext utilities - Updating Existing PO Files - - - - - - -

Go to the first, previous, next, last section, table of contents. -


- - -

Updating Existing PO Files

- - - -

Invoking the msgmerge Program

- - - -

Translated Entries

- -

-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. - -

-
- -
t -
-Find the next translated entry. - -
M-t -
-Find the previous translated entry. - -
- -

-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. - -

- - -

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. - -

-
- -
f -
-Find the next fuzzy entry. - -
M-f -
-Find the previous fuzzy entry. - -
TAB -
-Remove the fuzzy attribute of the current entry. - -
- -

-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. - -

- - -

Untranslated Entries

- -

-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. - -

-
- -
u -
-Find the next untranslated entry. - -
M-u -
-Find the previous untranslated entry. - -
k -
-Turn the current entry into an untranslated one. - -
- -

-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. - -

- - -

Obsolete Entries

- -

-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. - -

-
- -
o -
-Find the next obsolete entry. - -
M-o -
-Find the previous obsolete entry. - -
DEL -
-Make an active entry obsolete, or zap out an obsolete entry. - -
- -

-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. - -

- - -

Modifying Translations

- -

-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. - -

-
- -
RET -
-Interactively edit the translation. - -
LFD -
-Reinitialize the translation with the original, untranslated string. - -
k -
-Save the translation on the kill ring, and delete it. - -
w -
-Save the translation on the kill ring, without deleting it. - -
y -
-Replace the translation, taking the new from the kill ring. - -
- -

-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. - -

- - -

Modifying Comments

- -

-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. - -

-
- -
# -
-Interactively edit the translator comments. - -
K -
-Save the translator comments on the kill ring, and delete it. - -
W -
-Save the translator comments on the kill ring, without deleting it. - -
Y -
-Replace the translator comments, taking the new from the kill ring. - -
- -

-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. - -

- - -

Consulting Auxiliary PO Files

- -

-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. - -

-
- -
a -
-Seek auxiliary files for another translation for the same entry. - -
M-a -
-Switch to a particular auxiliary file. - -
A -
-Declare this PO file as an auxiliary file. - -
M-A -
-Remove this PO file from the list of auxiliary files. - -
- -

-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. - -