# HG changeset patch # User cmlenz # Date 1180510646 0 # Node ID b2492365f186bd221b705ab03d083503420358c3 # Parent f71ca60f2a4a8808fdbe9b42d3804814d34770b3 Forgot to check in the doc directory. diff --git a/doc/catalogs.txt b/doc/catalogs.txt new file mode 100644 --- /dev/null +++ b/doc/catalogs.txt @@ -0,0 +1,106 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +============================= +Working with Message Catalogs +============================= + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +Introduction +============ + +The ``gettext`` translation system enables you to mark any strings used in your +application as subject to localization, by wrapping them in functions such as +``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the +``gettext`` function is often aliased to ``_(str)``, so you can write:: + + print _("Hello") + +instead of just:: + + print "Hello" + +to make the string "Hello" localizable. + +Message catalogs are collections of translations for such localizable messages +used in an application. They are commonly stored in PO (Portable Object) and MO +(Machine Object) files, the formats of which are defined by the GNU `gettext`_ +tools and the GNU `translation project`_. + + .. _`gettext`: http://www.gnu.org/software/gettext/ + .. _`translation project`: http://sourceforge.net/projects/translation + +The general procedure for building message catalogs looks something like this: + + * use a tool (such as ``xgettext``) to extract localizable strings from the + code base and write them to a POT (PO Template) file. + * make a copy of the POT file for a specific locale (for example, "en_US") + and start translating the messages + * use a tool such as ``msgfmt`` to compile the locale PO file into an binary + MO file + * later, when code changes make it necessary to update the translations, you + regenerate the POT file and merge the changes into the various + locale-specific PO files, for example using ``msgmerge`` + +Python provides the `gettext module`_ as part of the standard library, which +enables applications to work with appropriately generated MO files. + + .. _`gettext module`: http://docs.python.org/lib/module-gettext.html + +As ``gettext`` provides a solid and well supported foundation for translating +application messages, Babel does not reinvent the wheel, but rather reuses this +infrastructure, and makes it easier to build message catalogs for Python +applications. + + +Message Extraction +================== + +Babel provides functionality similar to that of the ``xgettext`` program, +except that only extraction from Python source files is built-in, while support +for other file formats can be added using a simple extension mechanism. + +(TODO: more) + + +-------------------------- +Writing Extraction Methods +-------------------------- + +(TODO: write) + +--------------------- +``setup.py`` Commands +--------------------- + +(TODO: overview) + +See `Distutils/Setuptools Integration `_ for more information. + +------------------- +Command-line script +------------------- + +(TODO: overview) + +See `Command-Line Interface `_ for more information. + + +Extended ``Translations`` Class +=============================== + +Many web-based applications are composed of a variety of different components +(possibly using some kind of plugin system), and some of those components may +provide their own message catalogs that need to be integrated into the larger +system. + +To support this usage pattern, Babel provides a ``Translations`` class that is +derived from the ``GNUTranslations`` class in the ``gettext`` module. This +class adds a ``merge()`` method that takes another ``Translations`` instance, +and merges its contents into the catalog:: + + translations = Translations.load('main') + translations.merge(Translations.load('plugin1')) diff --git a/doc/cmdline.txt b/doc/cmdline.txt new file mode 100644 --- /dev/null +++ b/doc/cmdline.txt @@ -0,0 +1,37 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +====================== +Command-Line Interface +====================== + +Babel includes a command-line interface for working with message catalogs, +similar to the GNU ``xgettext`` program commonly available on Linux/Unix +systems. + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +pygettext +========= + +When properly installed, Babel provides a script called ``pygettext``, which can +be used to extract localized messages from a variety of files:: + + $ pygettext --help + usage: pygettext [options] dirname1 ... + + options: + --version show program's version number and exit + -h, --help show this help message and exit + --charset=CHARSET charset to use in the output + -k KEYWORDS, --keyword=KEYWORDS + keywords to look for in addition to the defaults. You + can specify multiple -k flags on the command line. + --no-location do not include location comments with filename and + line number + --omit-header do not include msgid "" entry in header + -o OUTPUT, --output=OUTPUT + path to the output POT file diff --git a/doc/display.txt b/doc/display.txt new file mode 100644 --- /dev/null +++ b/doc/display.txt @@ -0,0 +1,52 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +==================== +Locale Display Names +==================== + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +Introduction +============ + +While `message catalogs `_ allow you to localize any messages +in your application, there are a number of strings that are used in many +applications for which translations are readily available. + +Imagine for example you have a list of countries that users can choose from, +and you'd like to display the names of those countries in the language the +user prefers. Instead of translating all those country names yourself in your +application, you can make use of the translations provided by the locale data +included with Babel, which is based on the `Common Locale Data Repository +(CLDR) `_ developed and maintained by the `Unicode +Consortium `_. + + +The ``Locale`` Class +==================== + +You normally access such locale data through the `Locale`_ class provided +by Babel:: + + >>> from babel import Locale + >>> locale = Locale('en', 'US') + >>> locale.territories['US'] + u'United States' + >>> locale = Locale('es', 'MX') + >>> locale.territories['US'] + u'Estados Unidos' + +.. _`Locale`: api/babel.core.Locale-class.html + +In addition to country/territory names, the locale data also provides access to +names of languages, scripts, variants, time zones, and more. Some of the data +is closely related to `number and date formatting`_. + +Most of the corresponding ``Locale`` properties return dictionaries, where the +key is a code such as the ISO country and language codes. Consult the API +documentation for references to the relevant specifications. + +.. _`number and date formatting`: formatting.html diff --git a/doc/docutils.conf b/doc/docutils.conf new file mode 100644 --- /dev/null +++ b/doc/docutils.conf @@ -0,0 +1,9 @@ +[general] +input_encoding = utf-8 +strip_comments = yes +toc_backlinks = none + +[html4css1 writer] +embed_stylesheet = no +stylesheet = style/edgewall.css +xml_declaration = no diff --git a/doc/epydoc.conf b/doc/epydoc.conf new file mode 100644 --- /dev/null +++ b/doc/epydoc.conf @@ -0,0 +1,24 @@ +[epydoc] + +name: Documentation Index +url: ../index.html +modules: babel +verbosity: 1 + +# Extraction +docformat: restructuredtext +parse: yes +introspect: yes +exclude: .*\.tests.* +inheritance: listed +private: no +imports: no +include-log: no + +# HTML output +output: html +target: doc/api/ +css: doc/style/epydoc.css +top: babel +frames: no +sourcecode: no diff --git a/doc/formatting.txt b/doc/formatting.txt new file mode 100644 --- /dev/null +++ b/doc/formatting.txt @@ -0,0 +1,12 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +========================== +Number and Date Formatting +========================== + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,62 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +===== +Babel +===== + + +--------------------------------------------------- +Simple Internationalization for Python Applications +--------------------------------------------------- + +Babel is an integrated collection of utilities that assist in +internationalizing and localizing Python applications, with an +emphasis on web-based applications. + +* `Working with Message Catalogs `_ +* `Locale Display Names `_ +* `Number and Date Formatting `_ +* `Command-Line Interface `_ +* `Distutils/Setuptools Integration `_ +* `Generated API Documentation `_ + +Introduction +------------ + +The functionality Babel provides for internationalization (I18n) and +localization (L10N) can be separated into two different aspects: + + * tools to build and work with ``gettext`` message catalogs, and + * a Python interface to the CLDR (Common Locale Data Repository), providing + access to various locale display names, localized number and date + formatting, etc. + +While the Python standard library includes a +`gettext `_ module that enables +applications to use message catalogs, it requires developers to build these +catalogs using GNU tools such as ``xgettext``, ``msgmerge``, and ``msgfmt``. +And while ``xgettext`` does have support for extracting messages from Python +files, it does not know how to deal with other kinds of files commonly found +in Python web-applications, such as templates, nor does it provide an easy +extensibility mechanism to add such support. + +Babel addresses this by providing a framework where various extraction methods +can be plugged in to a larger message extraction framework, and also removes +the dependency on the GNU ``gettext`` tools for common tasks, as these aren't +necessarily available on all platforms. See `Working with Message Catalogs`_ +for details on this aspect of Babel. + +Furthermore, while the Python standard library does include support for basic +localization with respect to the formatting of numbers and dates (the +`locale `_ module, among others), +this support is based on the assumption that there will be only one specific +locale used per process (at least simultaneously.) Also, it doesn't provide +access to other kinds of locale data, such as the localized names of countries, +languages, or time zones, with are frequently needed in web-based applications. + +For these requirements, Babel includes data extracted from the `Common Locale +Data Repository (CLDR) `_, and provides a number of +convenient methods for accessing and using this data. See `Locale Display +Names`_ and `Number and Date Formatting`_ for more information on this aspect +of Babel. + diff --git a/doc/setup.txt b/doc/setup.txt new file mode 100644 --- /dev/null +++ b/doc/setup.txt @@ -0,0 +1,78 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +================================ +Distutils/Setuptools Integration +================================ + +Babel provides commands for integration into ``setup.py`` scripts, based on +either the ``distutils`` package that is part of the Python standard library, +or the third-party ``setuptools`` package. + +These commands are available by default when Babel has been properly installed, +and ``setup.py`` is using ``setuptools``. For projects that use plain old +``distutils``, the commands need to be registered explicitly, for example:: + + from distutils.core import setup + from babel.catalog import frontend as babel + + setup( + ... + cmd_class = {'extract_messages': babel.extract_messages} + ) + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +extract_messages +================ + +The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program: +it can extract localizable messages from a variety of difference source files, +and generate a PO (portable object) template file from the collected messages. + +If the command has been correctly installed or registered, another project's +``setup.py`` script should allow you to use the command:: + + $ ./setup.py extract_messages --help + Global options: + --verbose (-v) run verbosely (default) + --quiet (-q) run quietly (turns verbosity off) + --dry-run (-n) don't actually do anything + --help (-h) show detailed help message + + Options for 'extract_messages' command: + --charset charset to use in the output + --keywords (-k) comma-separated list of keywords to look for in addition + to the defaults + --no-location do not write filename/lineno location comments + --output-file filename of the output PO file + +Running the command will produce a PO file:: + + $ ./setup.py extract_messages --output-file webapp/locales/messages.pot + running extract_messages + extracting messages from 'webapp' + extracting messages from 'webparts' + writing PO file to webapp/locales/messages.pot + + +Options +------- + +As shown in the ``--help`` output above, the ``extract_messages`` command +accepts the following options: + +``--charset`` + The character set / encoding to use in the generated PO file. +``--keywords`` + A comma-separated list of keywords (function names) to look for in addition + to the default keywords +``--no-location`` + If this flag is set, location comments will not be included in the generated + PO file. +``--output-file`` or ``-o`` + The path to the PO file that should be generated + diff --git a/doc/style/bkgnd_pattern.png b/doc/style/bkgnd_pattern.png new file mode 100644 index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..90e92682135d3f7213332f870f973bd06d6d57ee GIT binary patch literal 112 zc%17D@N?(olHy`uVBq!ia0vp^B0wy_$P6TPuAPklQfvV}A+FxOzMSaRTj#)AV3j$Ayz@Myi$y`k~e02bnvp_D$RTJdd?9OQ`;xMNQr6-*0k%)gGDlIK1ArveB)f zy1Birqq{afsXt{x+N6vrS=0I^&YBz=ojG&P!l|%IowZOI~+1jT1O3(*SY z=AC!{^{#V=egxhBzNNG+Wcfh@o-JZ+A^YdBKeo7Z&60On=AvAqCA)Sc&P(TZUiF#( z^rj1DlCO7NijoNWTO^lr+bufXqg3k6Z@=t^|9Q_@g4NuszNO~8s$076@rDAqInO=8 zN?HUmba__RS@I|KY$^3?e!VMWHqT1EydCdvADZy$5&PrG?DFy^Z!PAn-4+0JID@CF KpUXO@geCwp5oi