.. role:: code(strong).. role:: file(emphasis)========================README file for po-utils========================PO utilities is meant to become a collection of tools for handling POfiles.  Until there is a real Texinfo manual for it, the documentationis kept in this :file:`README`.What are these PO and POT things?=================================There is an on-going effort so programs are made to comply with nationaldifferences, like the way of writing dates, currency, decimal numbernotations, and such things.  The preparation of programs towards thisgoal is called *internationalisation* (or *i18n* for short), and theon-the-fly adjustment of an already internationalised program to aparticular set of habits is called *localisation* (or *l10n* for short).Each particular set of habits for a given nation is called a *locale*.One important aspect of internationalisation is that programs should beable to write their messages and diagnostics in more than one language.This aspect is particularly demanding because, contrarily to otheraspects of a *locale* which are set once and for all, program messageshave to be translated separately for every programs, as originalmessages differ.A PO file is a pivoting point between maintainers of internationalisedprograms and various national translators.  Each particular PO fileholds, for a given package, the original program messages needingtranslation, and the translation of each of these messages into agiven national language.  That is, there is usually one PO file perpackage-language combination.  A PO file containing only originalmessages, and empty strings instead of translations, is called a POtemplate, or POT file.  Translators usually begin with a POT file, andturn it into a PO file by adding translations.While a package is being internationalised, each string used in theprogram is considered, and those who might need translation arespecially marked.  Some editing tools (like :code:`PO mode` in Emacs)have the purpose of easing that tedious marking task.  Then, other tools(like :code:`xpot`, :code:`pygettext` or :code:`xgettext`) have the purpose ofscanning a set of marked sources, and collecting all marked strings intoa POT file.  This POT file is given to translators, who add translations(:code:`PO mode` is helpful here as well).  Each resulting PO file iscompiled into an MO file (using :code:`msgfmt`) for faster access, andinstalled together with the package.  When the installed package runsin a given locale, one installed MO file is selected according to thelanguage of the user, and used to obtain the translated version ofmessages and diagnostics, as needed.:code:`PO mode`===============File :file:`po-mode.el` implements a set of Emacs editing functions forPO files.  It can be used by maintainers to mark translatable strings ina set of sources, or by translators to add or revise translations in aPO file.  The main documentation is currently part of the manual whichcomes in the :code:`gettext` distribution.:code:`xpot`============Introduction------------This tool produces a PO template file on standard output, given acollection of source files.  It currently handles C, C++, Emacs LISP,and Python sources, as well as from pre-existing PO files.  It is meantto handle Awk, Perl or shell scripts, when everything will be ready forthese.  And in fact, anything that could help internationalisation.To find out the language of a program, :code:`xpot` looks for hintsin the extension of the file name, or else, in the contents of thefirst two lines of the file, looking for ``#!PATH/env PROGRAM``,``#!PATH/PROGRAM``, ``-*-mode:MODE-*-`` or ``-*-MODE-*-`` in the firsttwo lines.:code:`xpot` is itself written in C, Flex and Bison, and I would expect itto be rather fast even for big projects.  This is an alpha version.Options-------One option to :code:`xpot` allows for automatic extraction of all docstrings, which never need explicit marking in either Emacs LISP orPython, for this reason.  Translation of doc string might be useful inhighly interactive programs, giving access to interpreter facilities.Emacs LISP----------Mule files, when a character uses many bytes, may not be analysedcorrectly.Python------Adjacent strings (those only separated by whitespace or comments) arecorrectly concatenated at extraction time.  Strings are consideredtranslatable if they are used within _(STRING) or gettext(STRING)constructs, other keywords may be added, of course.To palliate the lack of a pre-processor, strings which translationshould be delayed may be marked as translatable by using one of thefollowing special constructs, which are already valid Python::   ''"text"        ''r"text"   ""'text'        ""r'text'   ''"""text"""    ''r"""text"""   ""'''text'''    ""r'''text'''Doc strings, if their extraction has been selected, should be correctlyfound even after very complex initialisation of keyword parameters.