gettext: Marking
4.5 Marking Translatable Strings
================================
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, targeted 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 packages following the GNU coding standards, there is a make goal
‘tags’ or ‘TAGS’ which constructs 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.
‘,’
Search through program sources for a string which looks like a
candidate for translation (‘po-tags-search’).
‘M-,’
Mark the last string found with ‘_()’ (‘po-mark-translatable’).
‘M-.’
Mark the last string found with a keyword taken from a set of
possible keywords. This command with a prefix allows some
management of these keywords (‘po-select-mark-and-mark’).
The ‘,’ (‘po-tags-search’) command searches 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 too big to fit whole in this window, it is 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. ⇒Tag Tables
(emacs)Tags.
Each time you use the ‘,’ command, the search resumes from where it
was left 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 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 command ‘,’ 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.
Info Catalog
gettext: Mark Keywords
gettext: Sources
gettext: c-format Flag