Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
C Shell XSLT
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
.. role:: code(strong) .. role:: file(emphasis) ======================== README file for po-utils ======================== PO utilities is meant to become a collection of tools for handling PO files. Until there is a real Texinfo manual for it, the documentation is 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 national differences, like the way of writing dates, currency, decimal number notations, and such things. The preparation of programs towards this goal is called *internationalisation* (or *i18n* for short), and the on-the-fly adjustment of an already internationalised program to a particular 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 be able to write their messages and diagnostics in more than one language. This aspect is particularly demanding because, contrarily to other aspects of a *locale* which are set once and for all, program messages have to be translated separately for every programs, as original messages differ. A PO file is a pivoting point between maintainers of internationalised programs and various national translators. Each particular PO file holds, for a given package, the original program messages needing translation, and the translation of each of these messages into a given national language. That is, there is usually one PO file per package-language combination. A PO file containing only original messages, and empty strings instead of translations, is called a PO template, or POT file. Translators usually begin with a POT file, and turn it into a PO file by adding translations. While a package is being internationalised, each string used in the program is considered, and those who might need translation are specially 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 of scanning a set of marked sources, and collecting all marked strings into a POT file. This POT file is given to translators, who add translations (:code:`PO mode` is helpful here as well). Each resulting PO file is compiled into an MO file (using :code:`msgfmt`) for faster access, and installed together with the package. When the installed package runs in a given locale, one installed MO file is selected according to the language of the user, and used to obtain the translated version of messages and diagnostics, as needed. :code:`PO mode` =============== File :file:`po-mode.el` implements a set of Emacs editing functions for PO files. It can be used by maintainers to mark translatable strings in a set of sources, or by translators to add or revise translations in a PO file. The main documentation is currently part of the manual which comes in the :code:`gettext` distribution. :code:`xpot` ============ Introduction ------------ This tool produces a PO template file on standard output, given a collection of source files. It currently handles C, C++, Emacs LISP, and Python sources, as well as from pre-existing PO files. It is meant to handle Awk, Perl or shell scripts, when everything will be ready for these. And in fact, anything that could help internationalisation. To find out the language of a program, :code:`xpot` looks for hints in the extension of the file name, or else, in the contents of the first two lines of the file, looking for ``#!PATH/env PROGRAM``, ``#!PATH/PROGRAM``, ``-*-mode:MODE-*-`` or ``-*-MODE-*-`` in the first two lines. :code:`xpot` is itself written in C, Flex and Bison, and I would expect it to be rather fast even for big projects. This is an alpha version. Options ------- One option to :code:`xpot` allows for automatic extraction of all doc strings, which never need explicit marking in either Emacs LISP or Python, for this reason. Translation of doc string might be useful in highly interactive programs, giving access to interpreter facilities. Emacs LISP ---------- Mule files, when a character uses many bytes, may not be analysed correctly. Python ------ Adjacent strings (those only separated by whitespace or comments) are correctly concatenated at extraction time. Strings are considered translatable 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 translation should be delayed may be marked as translatable by using one of the following 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 correctly found even after very complex initialisation of keyword parameters.