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