(gettext) Marking

Info Catalog (gettext) Mark Keywords (gettext) Sources (gettext) c-format Flag
 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
    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').
      Mark the last string found with `_()' (`po-mark-translatable').
      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
automatically generated byinfo2html