extraction methods, which is described below.
+Babel provides two different front-ends to access its functionality for working
+ * A `Command-line interface <cmdline.html>`_, and
+ * `Integration with distutils/setuptools <setup.html>`_
+Which one you choose depends on the nature of your project. For most modern
+Python projects, the distutils/setuptools integration is probably more
# Extraction from Python source files
# Extraction from Genshi HTML and text templates
+ [genshi: **/templates/**.html]
ignore_tags = script,style
include_attrs = alt title summary
+ [genshi: **/templates/**.txt]
template_class = genshi.template:TextTemplate
The configuration file syntax is based on the format commonly found in ``.INI``
files on Windows systems, and as supported by the ``ConfigParser`` module in
-the Python standard librar
ies. Section names (the strings enclosed in square
+the Python standard librar. Section names (the strings enclosed in square
brackets) specify both the name of the extraction method, and the extended glob
pattern to specify the files that this extraction method should be used for,
separated by a colon. The options in the sections are passed to the extraction
extension ``.txt`` in any directory.
Lines that start with a ``#`` or ``;`` character are ignored and can be used
-for comments. Empty lines are
also ignored, too.
+for comments. Empty lines are ignored, too.
.. note:: if you're performing message extraction using the command Babel
- provides for integration into ``setup.py`` scripts (see below), you
- can also provide this configuration in a different way, namely as a
- keyword argument to the ``setup()`` function.
+ provides for integration into ``setup.py`` scripts, you can also
+ provide this configuration in a different way, namely as a keyword
+ argument to the ``setup()`` function. See `Distutils/Setuptools
+ Integration`_ for more information.
+.. _`distutils/setuptools integration`: setup.html
-Babel provides two different front-ends to access its functionality for working
+Default Extraction Methods
- * A `Command-line interface <cmdline.html>`_, and
- * `Integration with distutils/setuptools <setup.html>`_
+Babel comes with only two builtin extractors: ``python`` (which extracts
+messages from Python source files) and ``ignore`` (which extracts nothing).
-Which one you choose depends on the nature of your project. For most modern
-Python projects, the distutils/setuptools integration is probably more
+The ``python`` extractor is by default mapped to the glob pattern ``**.py``,
+meaning it'll be applied to all files with the ``.py`` extension in any
+directory. If you specify your own mapping configuration, this default mapping
+is not discarded, so you need to explicitly add it to your mapping (as shown in
+.. _`referencing extraction methods`:
+Referencing Extraction Methods
+To be able to use short extraction method names such as “genshi”, you need to
+have `pkg_resources`_ installed, and the package implementing that extraction
+method needs to have been installed with its meta data (the `egg-info`_).
+If this is not possible for some reason, you need to map the short names to
+fully qualified function names in an extract section in the mapping
+configuration. For example:
+ # Some custom extraction method
+ custom = mypackage.module:extract_custom
+Note that the builtin extraction methods ``python`` and ``ignore`` are available
+by default, even if `pkg_resources`_ is not installed. You should never need to
+explicitly define them in the ``[extractors]`` section.
+.. _`egg-info`: http://peak.telecommunity.com/DevCenter/PythonEggs
+.. _`pkg_resources`: http://peak.telecommunity.com/DevCenter/PkgResources
the name of the function (separated by a colon) implementing the actual
+.. note:: As shown in `Referencing Extraction Methods`_, declaring an entry
+ point is not strictly required, as users can still reference the
+ extraction function directly. But whenever possible, the entry point
+ should be declared to make configuration more convenient.
.. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
-Comments Tags And Translator Comments Explanation
First of all what are comments tags. Comments tags are excerpts of text to
search for in comments, only comments, right before the `python gettext`_
Now, you might ask, why would I need that?
-Consider this simple case; you have a menu item called “
Manual”. You know what
+Consider this simple case; you have a menu item called “anual”. You know what
it means, but when the translator sees this they will wonder did you mean:
1. a document or help manual, or
“The installation manual” helps to clarify the situation and makes a translator
-**More examples of the need for translation comments**
-Real world examples are best. This is a discussion over the use of the word
-“Forward” in Northern Sotho:
-“When you go forward. You go ‘Pele’, but when you forward the document,
-you ‘Fetišetša pele’. So if you just say forward, we don’t know what you are
-It is better if it's in a sentence. But in this case i think we will use ‘pele’
-because on the string no. 86 and 88 there is “show previous page in history”
-and “show next page in history”.
-Were the translators guess correct? I think so, but it makes it so much easier
-if they don’t need to be super `sleuths`_ as well as translators.
- .. _`sleuths`: http://www.thefreedictionary.com/sleuth
-*Explanation Borrowed From:* `Wordforge`_
- .. _`Wordforge`: http://www.wordforge.org/static/translation_comments.html
-**Note**: Translator comments are currently only supported in python source
+.. note:: Whether translator comments can be extracted depends on the extraction
+ method in use. The Python extractor provided by Babel does implement
+ this feature, but others may not.