Mercurial > babel > old > babel-test

comparison doc/catalogs.txt @ 48:bd647e3760e0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Move the mapping configuration file format to `ConfigParser`, and add some more documentation about it.
author cmlenz
date Wed, 06 Jun 2007 23:17:18 +0000
parents 4525549aa6cc
children daf35e2ad044
comparison
equal deleted inserted replaced
47:76381d4b3635 48:bd647e3760e0
65 65
66 Babel provides functionality similar to that of the ``xgettext`` program, 66 Babel provides functionality similar to that of the ``xgettext`` program,
67 except that only extraction from Python source files is built-in, while support 67 except that only extraction from Python source files is built-in, while support
68 for other file formats can be added using a simple extension mechanism. 68 for other file formats can be added using a simple extension mechanism.
69 69
70 (TODO: more) 70 Unlike ``xgettext``, which is usually invoked once for every file, the routines
71 for message extraction in Babel operate on directories. While the per-file
72 approach of ``xgettext`` works nicely with projects using a ``Makefile``,
73 Python projects rarely use ``make``, and thus a different mechanism is needed
74 for extracting messages from the heterogeneous collection of source files that
75 many Python projects are composed of.
76
77 When message extraction is based on directories instead of individual files,
78 there needs to be a way to configure which files should be treated in which
79 manner. For example, while many projects may contain ``.html`` files, some of
80 those files may be static HTML files that don't contain localizable message,
81 while others may be `Django`_ templates, and still others may contain `Genshi`_
82 markup templates. Some projects may even mix HTML files for different templates
83 languages (for whatever reason). Therefore the way in which messages are
84 extracted from source files can not only depend on the file extension, but
85 needs to be controllable in a precise manner.
86
87 .. _`Django`: http://www.djangoproject.com/
88 .. _`Genshi`: http://genshi.edgewall.org/
89
90 Babel accepts a configuration file to specify this mapping of files to
91 extraction methods, which is described below.
71 92
72 93
73 -------------------------- 94 .. _`mapping`:
74 Writing Extraction Methods
75 --------------------------
76 95
77 (TODO: write) 96 -------------------------------------------
97 Extraction Method Mapping and Configuration
98 -------------------------------------------
99
100 The mapping of extraction methods to files in Babel is done via a configuration
101 file. This file maps extended glob patterns to the names of the extraction
102 methods, and can also set various options for each pattern (which options are
103 available depends on the specific extraction method).
104
105 For example, the following configuration adds extraction of messages from both
106 Genshi markup templates and text templates:
107
108 .. code-block:: ini
109
110 # Extraction from Python source files
111
112 [python: foobar/**.py]
113
114 # Extraction from Genshi HTML and text templates
115
116 [genshi: foobar/**/templates/**.html]
117 ignore_tags = script,style
118 include_attrs = alt title summary
119
120 [genshi: foobar/**/templates/**.txt]
121 template_class = genshi.template.text:TextTemplate
122 encoding = ISO-8819-15
123
124 The configuration file syntax is based on the format commonly found in ``.INI``
125 files on Windows systems, and as supported by the ``ConfigParser`` module in
126 the Python standard libraries. Section names (the strings enclosed in square
127 brackets) specify both the name of the extraction method, and the extended glob
128 pattern to specify the files that this extraction method should be used for,
129 separated by a colon. The options in the sections are passed to the extraction
130 method. Which options are available is specific to the extraction method used.
131
132 The extended glob patterns used in this configuration are similar to the glob
133 patterns provided by most shells. A single asterisk (``*``) is a wildcard for
134 any number of characters (except for the pathname component separator "/"),
135 while a question mark (``?``) only matches a single character. In addition,
136 two subsequent asterisk characters (``**``) can be used to make the wildcard
137 match any directory level, so the pattern ``**.txt`` matches any file with the
138 extension ``.txt`` in any directory.
139
140 Lines that start with a ``#`` or ``;`` character are ignored and can be used
141 for comments. Empty lines are also ignored, too.
142
78 143
79 --------------------- 144 ---------------------
80 ``setup.py`` Commands 145 ``setup.py`` Commands
81 --------------------- 146 ---------------------
82 147
90 155
91 (TODO: overview) 156 (TODO: overview)
92 157
93 See `Command-Line Interface <cmdline.html>`_ for more information. 158 See `Command-Line Interface <cmdline.html>`_ for more information.
94 159
160 --------------------------
161 Writing Extraction Methods
162 --------------------------
163
164 (TODO: write)
165
166
95 167
96 Extended ``Translations`` Class 168 Extended ``Translations`` Class
97 =============================== 169 ===============================
98 170
99 Many web-based applications are composed of a variety of different components 171 Many web-based applications are composed of a variety of different components
102 system. 174 system.
103 175
104 To support this usage pattern, Babel provides a ``Translations`` class that is 176 To support this usage pattern, Babel provides a ``Translations`` class that is
105 derived from the ``GNUTranslations`` class in the ``gettext`` module. This 177 derived from the ``GNUTranslations`` class in the ``gettext`` module. This
106 class adds a ``merge()`` method that takes another ``Translations`` instance, 178 class adds a ``merge()`` method that takes another ``Translations`` instance,
107 and merges its contents into the catalog:: 179 and merges its contents into the catalog:
108 180
109 .. code-block:: python 181 .. code-block:: python
110 182
111 translations = Translations.load('main') 183 translations = Translations.load('main')
112 translations.merge(Translations.load('plugin1')) 184 translations.merge(Translations.load('plugin1'))
Copyright (C) 2012-2017 Edgewall Software