setup.txt 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342
  1. .. -*- mode: rst; encoding: utf-8 -*-
  2. ================================
  3. Distutils/Setuptools Integration
  4. ================================
  5. Babel provides commands for integration into ``setup.py`` scripts, based on
  6. either the ``distutils`` package that is part of the Python standard library,
  7. or the third-party ``setuptools`` package.
  8. These commands are available by default when Babel has been properly installed,
  9. and ``setup.py`` is using ``setuptools``. For projects that use plain old
  10. ``distutils``, the commands need to be registered explicitly, for example:
  11. .. code-block:: python
  12. from distutils.core import setup
  13. from babel.messages import frontend as babel
  14. setup(
  15. ...
  16. cmdclass = {'compile_catalog': babel.compile_catalog,
  17. 'extract_messages': babel.extract_messages,
  18. 'init_catalog': babel.init_catalog,
  19. 'update_catalog': babel.update_catalog}
  20. )
  21. .. contents:: Contents
  22. :depth: 2
  23. .. sectnum::
  24. compile_catalog
  25. ===============
  26. The ``compile_catalog`` command is similar to the GNU ``msgfmt`` tool, in that
  27. it takes a message catalog from a PO file and compiles it to a binary MO file.
  28. If the command has been correctly installed or registered, a project's
  29. ``setup.py`` script should allow you to use the command::
  30. $ ./setup.py compile_catalog --help
  31. Global options:
  32. --verbose (-v) run verbosely (default)
  33. --quiet (-q) run quietly (turns verbosity off)
  34. --dry-run (-n) don't actually do anything
  35. --help (-h) show detailed help message
  36. Options for 'compile_catalog' command:
  37. ...
  38. Running the command will produce a binary MO file::
  39. $ ./setup.py compile_catalog --directory foobar/locale --locale pt_BR
  40. running compile_catalog
  41. compiling catalog to foobar/locale/pt_BR/LC_MESSAGES/messages.mo
  42. Options
  43. -------
  44. The ``compile_catalog`` command accepts the following options:
  45. +-----------------------------+---------------------------------------------+
  46. | Option | Description |
  47. +=============================+=============================================+
  48. | ``--domain`` | domain of the PO file (defaults to |
  49. | | lower-cased project name) |
  50. +-----------------------------+---------------------------------------------+
  51. | ``--directory`` (``-d``) | name of the base directory |
  52. +-----------------------------+---------------------------------------------+
  53. | ``--input-file`` (``-i``) | name of the input file |
  54. +-----------------------------+---------------------------------------------+
  55. | ``--output-file`` (``-o``) | name of the output file |
  56. +-----------------------------+---------------------------------------------+
  57. | ``--locale`` (``-l``) | locale for the new localized string |
  58. +-----------------------------+---------------------------------------------+
  59. | ``--use-fuzzy`` (``-f``) | also include "fuzzy" translations |
  60. +-----------------------------+---------------------------------------------+
  61. | ``--statistics`` | print statistics about translations |
  62. +-----------------------------+---------------------------------------------+
  63. If ``directory`` is specified, but ``output-file`` is not, the default filename
  64. of the output file will be::
  65. <directory>/<locale>/LC_MESSAGES/<domain>.mo
  66. If neither the ``input_file`` nor the ``locale`` option is set, this command
  67. looks for all catalog files in the base directory that match the given domain,
  68. and compiles each of them to MO files in the same directory.
  69. These options can either be specified on the command-line, or in the
  70. ``setup.cfg`` file.
  71. extract_messages
  72. ================
  73. The ``extract_messages`` command is comparable to the GNU ``xgettext`` program:
  74. it can extract localizable messages from a variety of difference source files,
  75. and generate a PO (portable object) template file from the collected messages.
  76. If the command has been correctly installed or registered, a project's
  77. ``setup.py`` script should allow you to use the command::
  78. $ ./setup.py extract_messages --help
  79. Global options:
  80. --verbose (-v) run verbosely (default)
  81. --quiet (-q) run quietly (turns verbosity off)
  82. --dry-run (-n) don't actually do anything
  83. --help (-h) show detailed help message
  84. Options for 'extract_messages' command:
  85. ...
  86. Running the command will produce a PO template file::
  87. $ ./setup.py extract_messages --output-file foobar/locale/messages.pot
  88. running extract_messages
  89. extracting messages from foobar/__init__.py
  90. extracting messages from foobar/core.py
  91. ...
  92. writing PO template file to foobar/locale/messages.pot
  93. Method Mapping
  94. --------------
  95. The mapping of file patterns to extraction methods (and options) can be
  96. specified using a configuration file that is pointed to using the
  97. ``--mapping-file`` option shown above. Alternatively, you can configure the
  98. mapping directly in ``setup.py`` using a keyword argument to the ``setup()``
  99. function:
  100. .. code-block:: python
  101. setup(...
  102. message_extractors = {
  103. 'foobar': [
  104. ('**.py', 'python', None),
  105. ('**/templates/**.html', 'genshi', None),
  106. ('**/templates/**.txt', 'genshi', {
  107. 'template_class': 'genshi.template:TextTemplate'
  108. })
  109. ],
  110. },
  111. ...
  112. )
  113. Options
  114. -------
  115. The ``extract_messages`` command accepts the following options:
  116. +-----------------------------+----------------------------------------------+
  117. | Option | Description |
  118. +=============================+==============================================+
  119. | ``--charset`` | charset to use in the output file |
  120. +-----------------------------+----------------------------------------------+
  121. | ``--keywords`` (``-k``) | space-separated list of keywords to look for |
  122. | | in addition to the defaults |
  123. +-----------------------------+----------------------------------------------+
  124. | ``--no-default-keywords`` | do not include the default keywords |
  125. +-----------------------------+----------------------------------------------+
  126. | ``--mapping-file`` (``-F``) | path to the mapping configuration file |
  127. +-----------------------------+----------------------------------------------+
  128. | ``--no-location`` | do not include location comments with |
  129. | | filename and line number |
  130. +-----------------------------+----------------------------------------------+
  131. | ``--omit-header`` | do not include msgid "" entry in header |
  132. +-----------------------------+----------------------------------------------+
  133. | ``--output-file`` (``-o``) | name of the output file |
  134. +-----------------------------+----------------------------------------------+
  135. | ``--width`` (``-w``) | set output line width (default 76) |
  136. +-----------------------------+----------------------------------------------+
  137. | ``--no-wrap`` | do not break long message lines, longer than |
  138. | | the output line width, into several lines |
  139. +-----------------------------+----------------------------------------------+
  140. | ``--input-dirs`` | directories that should be scanned for |
  141. | | messages |
  142. +-----------------------------+----------------------------------------------+
  143. | ``--sort-output`` | generate sorted output (default False) |
  144. +-----------------------------+----------------------------------------------+
  145. | ``--sort-by-file`` | sort output by file location (default False) |
  146. +-----------------------------+----------------------------------------------+
  147. | ``--msgid-bugs-address`` | set email address for message bug reports |
  148. +-----------------------------+----------------------------------------------+
  149. | ``--copyright-holder`` | set copyright holder in output |
  150. +-----------------------------+----------------------------------------------+
  151. | ``--add-comments (-c)`` | place comment block with TAG (or those |
  152. | | preceding keyword lines) in output file. |
  153. | | Separate multiple TAGs with commas(,) |
  154. +-----------------------------+----------------------------------------------+
  155. These options can either be specified on the command-line, or in the
  156. ``setup.cfg`` file. In the latter case, the options above become entries of the
  157. section ``[extract_messages]``, and the option names are changed to use
  158. underscore characters instead of dashes, for example:
  159. .. code-block:: ini
  160. [extract_messages]
  161. keywords = _, gettext, ngettext
  162. mapping_file = babel.cfg
  163. width = 80
  164. This would be equivalent to invoking the command from the command-line as
  165. follows::
  166. $ setup.py extract_messages -k _ -k gettext -k ngettext -F mapping.cfg -w 80
  167. Any path names are interpreted relative to the location of the ``setup.py``
  168. file. For boolean options, use "true" or "false" values.
  169. init_catalog
  170. ============
  171. The ``init_catalog`` command is basically equivalent to the GNU ``msginit``
  172. program: it creates a new translation catalog based on a PO template file (POT).
  173. If the command has been correctly installed or registered, a project's
  174. ``setup.py`` script should allow you to use the command::
  175. $ ./setup.py init_catalog --help
  176. Global options:
  177. --verbose (-v) run verbosely (default)
  178. --quiet (-q) run quietly (turns verbosity off)
  179. --dry-run (-n) don't actually do anything
  180. --help (-h) show detailed help message
  181. Options for 'init_catalog' command:
  182. ...
  183. Running the command will produce a PO file::
  184. $ ./setup.py init_catalog -l fr -i foobar/locales/messages.pot \
  185. -o foobar/locales/fr/messages.po
  186. running init_catalog
  187. creating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
  188. Options
  189. -------
  190. The ``init_catalog`` command accepts the following options:
  191. +-----------------------------+---------------------------------------------+
  192. | Option | Description |
  193. +=============================+=============================================+
  194. | ``--domain`` | domain of the PO file (defaults to |
  195. | | lower-cased project name) |
  196. +-----------------------------+---------------------------------------------+
  197. | ``--input-file`` (``-i``) | name of the input file |
  198. +-----------------------------+---------------------------------------------+
  199. | ``--output-dir`` (``-d``) | name of the output directory |
  200. +-----------------------------+---------------------------------------------+
  201. | ``--output-file`` (``-o``) | name of the output file |
  202. +-----------------------------+---------------------------------------------+
  203. | ``--locale`` | locale for the new localized string |
  204. +-----------------------------+---------------------------------------------+
  205. If ``output-dir`` is specified, but ``output-file`` is not, the default filename
  206. of the output file will be::
  207. <output_dir>/<locale>/LC_MESSAGES/<domain>.po
  208. These options can either be specified on the command-line, or in the
  209. ``setup.cfg`` file.
  210. update_catalog
  211. ==============
  212. The ``update_catalog`` command is basically equivalent to the GNU ``msgmerge``
  213. program: it updates an existing translations catalog based on a PO template
  214. file (POT).
  215. If the command has been correctly installed or registered, a project's
  216. ``setup.py`` script should allow you to use the command::
  217. $ ./setup.py update_catalog --help
  218. Global options:
  219. --verbose (-v) run verbosely (default)
  220. --quiet (-q) run quietly (turns verbosity off)
  221. --dry-run (-n) don't actually do anything
  222. --help (-h) show detailed help message
  223. Options for 'update_catalog' command:
  224. ...
  225. Running the command will update a PO file::
  226. $ ./setup.py update_catalog -l fr -i foobar/locales/messages.pot \
  227. -o foobar/locales/fr/messages.po
  228. running update_catalog
  229. updating catalog 'foobar/locales/fr/messages.po' based on 'foobar/locales/messages.pot'
  230. Options
  231. -------
  232. The ``update_catalog`` command accepts the following options:
  233. +-------------------------------------+-------------------------------------+
  234. | Option | Description |
  235. +=====================================+=====================================+
  236. | ``--domain`` | domain of the PO file (defaults to |
  237. | | lower-cased project name) |
  238. +-------------------------------------+-------------------------------------+
  239. | ``--input-file`` (``-i``) | name of the input file |
  240. +-------------------------------------+-------------------------------------+
  241. | ``--output-dir`` (``-d``) | name of the output directory |
  242. +-------------------------------------+-------------------------------------+
  243. | ``--output-file`` (``-o``) | name of the output file |
  244. +-------------------------------------+-------------------------------------+
  245. | ``--locale`` | locale for the new localized string |
  246. +-------------------------------------+-------------------------------------+
  247. | ``--ignore-obsolete`` | do not include obsolete messages in |
  248. | | the output |
  249. +-------------------------------------+-------------------------------------+
  250. | ``--no-fuzzy-matching`` (``-N``) | do not use fuzzy matching |
  251. +-------------------------------------+-------------------------------------+
  252. | ``--previous`` | keep previous msgids of translated |
  253. | | messages |
  254. +-------------------------------------+-------------------------------------+
  255. If ``output-dir`` is specified, but ``output-file`` is not, the default filename
  256. of the output file will be::
  257. <output_dir>/<locale>/LC_MESSAGES/<domain>.po
  258. If neither the ``input_file`` nor the ``locale`` option is set, this command
  259. looks for all catalog files in the base directory that match the given domain,
  260. and updates each of them.
  261. These options can either be specified on the command-line, or in the
  262. ``setup.cfg`` file.