In PO mode, one set of features is meant more for the programmer than for the translator, and allows him to interactively mark which strings, in a set of program sources, are translatable, and which are not. Even if it is a fairly easy job for a programmer to find and mark such strings by other means, using any editor of his choice, PO mode makes this work more comfortable. Further, this gives translators who feel a little like programmers, or programmers who feel a little like translators, a tool letting them work at marking translatable strings in the program sources, while simultaneously producing a set of translation in some language, for the package being internationalized.
The set of program sources, aimed by the PO mode commands describe here, should have an Emacs tags table constructed for your project, prior to using these PO file commands. This is easy to do. In any shell window, change the directory to the root of your project, then execute a command resembling:
etags src/*.[hc] lib/*.[hc]
presuming here you want to process all `.h' and `.c' files from the `src/' and `lib/' directories. This command will explore all said files and create a `TAGS' file in your root directory, somewhat summarizing the contents using a special file format Emacs can understand.
For official GNU packages which follow the GNU coding standard there is
a make goal tags or TAGS which construct the tag files in
all directories and for all files containing source code.
Once your `TAGS' file is ready, the following commands assist the programmer at marking translatable strings in his set of sources. But these commands are necessarily driven from within a PO file window, and it is likely that you do not even have such a PO file yet. This is not a problem at all, as you may safely open a new, empty PO file, mainly for using these commands. This empty PO file will slowly fill in while you mark strings as translatable in your program sources.
The , (po-tags-search) command search for the next
occurrence of a string which looks like a possible candidate for
translation, and displays the program source in another Emacs window,
positioned in such a way that the string is near the top of this other
window. If the string is to big to fit whole in this window, it is
rather positioned so only its end is shown. In any case, the cursor
is left in the PO file window. If the shown string would be better
presented differently in different native languages, you may mark it
using M-, or M-.. Otherwise, you might rather ignore it
and skip to the next string by merely repeating the , command.
A string is a good candidate for translation if it contains a sequence of three or more letters. A string containing at most two letters in a row will be considered as a candidate if it has more letters than non-letters. The command disregards strings containing no letters, or isolated letters only. It also disregards strings within comments, or strings already marked with some keyword PO mode knows (see below).
If you have never told Emacs about some `TAGS' file to use, the command will request that you specify one from the minibuffer, the first time you use the command. You may later change your `TAGS' file by using the regular Emacs command M-x visit-tags-table, which will ask you to name the precise `TAGS' file you want to use. See section `Tag Tables' in The Emacs Editor.
Each time you use the , command, the search resumes where it was left over by the previous search, and goes through all program sources, obeying the `TAGS' file, until all sources have been processed. However, by giving a prefix argument to the command (C-u ,), you may request that the search be restarted all over again from the first program source; but in this case, strings that you recently marked as translatable will be automatically skipped.
Using this , command does not prevent using of other regular
Emacs tags commands. For example, regular tags-search or
tags-query-replace commands may be used without disrupting the
independent , search sequence. However, as implemented, the
initial , command (or the , command is used with a
prefix) might also reinitialize the regular Emacs tags searching to the
first tags file, this reinitialization might be considered spurious.
The M-, (po-mark-translatable) command will mark the
recently found string with the `_' keyword. The M-.
(po-select-mark-and-mark) command will request that you type
one keyword from the minibuffer and use that keyword for marking
the string. Both commands will automatically create a new PO file
untranslated entry for the string being marked, and make it the
current entry (making it easy for you to immediately proceed to its
translation, if you feel like doing it right away). It is possible
that the modifications made to the program source by M-, or
M-. render some source line longer than 80 columns, forcing you
to break and re-indent this line differently. You may use the o
command from PO mode, or any other window changing command from
GNU Emacs, to break out into the program source window, and do any
needed adjustments. You will have to use some regular Emacs command
to return the cursor to the PO file window, if you want commanding
, for the next string, say.
The M-. command has a few built-in speedups, so you do not have to explicitly type all keywords all the time. The first such speedup is that you are presented with a preferred keyword, which you may accept by merely typing RET at the prompt. The second speedup is that you may type any non-ambiguous prefix of the keyword you really mean, and the command will complete it automatically for you. This also means that PO mode has to know all your possible keywords, and that it will not accept mistyped keywords.
If you reply ? to the keyword request, the command gives a list of all known keywords, from which you may choose. When the command is prefixed by an argument (C-u M-.), it inhibits updating any program source or PO file buffer, and does some simple keyword management instead. In this case, the command asks for a keyword, written in full, which becomes a new allowed keyword for later M-. commands. Moreover, this new keyword automatically becomes the preferred keyword for later commands. By typing an already known keyword in response to C-u M-., one merely changes the preferred keyword and does nothing more.
All keywords known for M-. are recognized by the , command when scanning for strings, and strings already marked by any of those known keywords are automatically skipped. If many PO files are opened simultaneously, each one has its own independent set of known keywords. There is no provision in PO mode, currently, for deleting a known keyword, you have to quit the file (maybe using q) and reopen it afresh. When a PO file is newly brought up in an Emacs window, only `gettext' and `_' are known as keywords, and `gettext' is preferred for the M-. command. In fact, this is not useful to prefer `_', as this one is already built in the M-, command.
Go to the first, previous, next, last section, table of contents.