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