PKG-INFO 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487
  1. Metadata-Version: 1.1
  2. Name: django-babel
  3. Version: 0.6.2
  4. Summary: Utilities for using Babel in Django
  5. Home-page: https://github.com/python-babel/django-babel/
  6. Author: Thomas Grainger
  7. Author-email: django-babel@graingert.co.uk
  8. License: BSD
  9. Description-Content-Type: UNKNOWN
  10. Description: Tools for using Babel with Django
  11. =================================
  12. This package contains various utilities for integration of `Babel`_ into the
  13. `Django`_ web framework:
  14. * A message extraction plugin for Django templates.
  15. * A middleware class that adds the Babel `Locale`_ object to requests.
  16. * A set of template tags for date and number formatting.
  17. Extracting Messages
  18. -------------------
  19. Babel provides a message extraction framework similar to GNU ``xgettext``, but
  20. more extensible and geared towards Python applications. While Django does
  21. provide `wrapper scripts`_ for making the use of ``xgettext`` more
  22. convenient, the extraction functionality is rather limited. For example, you
  23. can't use template files with an extension other than ``.html``, and everything
  24. needs to be in your project package directory.
  25. Extraction Method Mapping
  26. ^^^^^^^^^^^^^^^^^^^^^^^^^
  27. So django-babel comes with an extraction method plugin that can extract
  28. localizable messages from Django template files. Python is supported out of the
  29. box by Babel. To use this extraction functionality, create a file called
  30. ``babel.cfg`` in your project directory (the directory above your project
  31. package), with the content:
  32. .. code-block:: ini
  33. [django: templates/**.*]
  34. [django: mypkg/*/templates/**.*]
  35. [python: mypkg/**.py]
  36. This instructs Babel to look for any files in the top-level ``templates``
  37. directory, or any files in application ``templates`` directories, and use the
  38. extraction method named “django” to extract messages from those template files.
  39. You'll need to adjust those glob patterns to wherever you my be storing your
  40. templates.
  41. Also, any files with the extension ``.py`` inside your package directory (replace
  42. “mypkg” with the actual name of your Django project package) are processed by
  43. the “python” extraction method.
  44. If you don't use setuptools, or for some reason haven't installed django-babel
  45. using setuptools/pip, you'll need to define what function the extraction method
  46. “django” maps to. This is done in an extra section at the top of the
  47. configuration file:
  48. .. code-block:: ini
  49. [extractors]
  50. django = django_babel.extract:extract_django
  51. The encoding of the templates is assumed to be UTF-8. If you are using a
  52. different encoding, you will need to specify it in the configuration. For
  53. example:
  54. .. code-block:: ini
  55. [django: templates/**.*]
  56. encoding = iso-8859-1
  57. Running the Extraction Process
  58. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  59. Once you've set up the configuration file, the actual extraction is performed
  60. by executing the command-line program ``pybabel`` which is installed alongside
  61. the Babel package:
  62. .. code-block:: bash
  63. $ cd projectdir
  64. $ pybabel extract -F babel.cfg -o mypkg/locale/django.pot .
  65. This creates the PO file template in ``mypkg/locale/django.pot``.
  66. Creating and Updating Translations Catalogs
  67. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  68. If you don't already have translation catalogs, you need to create them. This
  69. is done using the ``pybabel init`` command:
  70. .. code-block:: bash
  71. $ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l en_US
  72. $ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l de_DE
  73. This should create two files: ``mypkg/locale/en_US/django.po`` and
  74. ``mypkg/locale/de_DE/django.po``. These files are where you put the actual
  75. translations.
  76. When you modify your Python source files or your templates, you genereally need
  77. to sync the translation catalogs. For that, you first perform a fresh
  78. extraction as described in the previous section, so that the ``django.pot`` file
  79. gets updated.
  80. Then, you run the ``pybabel update`` command to merge the changes into the
  81. translation catalogs:
  82. ```bash
  83. $ pybabel update -D django -i mypkg/locale/django.pot -d mypkg/locale
  84. ```
  85. This will update all the ``.po`` files found in the ``mypkg/locale`` directory.
  86. Compiling Translations Catalogs
  87. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  88. Finally, you need to compile those ``.po`` files to binary ``.mo`` files. Use the
  89. `pybabel compile` command for that:
  90. .. code-block:: bash
  91. $ pybabel compile -D django -d mypkg/locale
  92. Add the ``--statistics`` option to get information about the completeness of your
  93. translations:
  94. .. code-block:: bash
  95. $ pybabel compile -D django -d mypkg/locale --statistics
  96. Using ``setup.py``
  97. ^^^^^^^^^^^^^^^^^^
  98. Much of the above process can be automated if you add a ``setup.py`` script to
  99. your project and use the distutils/setuptools commands that come with Babel.
  100. This is described at `Distutils/Setuptools Integration`_.
  101. Using the Middleware
  102. --------------------
  103. To use the Babel middleware, add it to the list of ``MIDDLEWARE_CLASSES`` in your
  104. settings module. If you're also using Django's own ``LocaleMiddleware`` to vary
  105. the locale based on user preference, the Babel middleware must be inserted
  106. after the Django one:
  107. .. code-block:: python
  108. MIDDLEWARE_CLASSES = (
  109. ...
  110. 'django.middleware.locale.LocaleMiddleware',
  111. 'django_babel.middleware.LocaleMiddleware',
  112. ...
  113. )
  114. This adds a ``locale`` attribute to the request object, which is an instance of
  115. the Babel ``Locale`` class. You can access the locale via ``request.locale`` when
  116. the request object is available, or otherwise use the
  117. ``django_babel.middleware.get_current_locale()`` function to get the current
  118. locale from a thread-local cache.
  119. Using the Template Tags
  120. -----------------------
  121. The template filters provided by django-babel allow formatting of date/time and
  122. number values in a locale-sensitive manner, providing much more powerful
  123. alternatives to the ``date``, ``time``, and ``floatformat`` filters that come with
  124. Django.
  125. To make the template filters/tags available, you need to add django-babel to
  126. the list of ``INSTALLED_APPS`` in your settings module:
  127. .. code-block:: python
  128. INSTALLED_APPS = (
  129. ...
  130. 'django_babel',
  131. ...
  132. )
  133. And in every template you want to use the filters, you need to explicitly load
  134. the django-babel library:
  135. .. code-block:: django
  136. {% load babel %}
  137. General information on date/time and number formatting can be found at
  138. `Date Formatting`_ and `Number Formatting`_.
  139. The following filters are made available. The examples assume a locale of
  140. ``en_US``.
  141. ``datefmt``
  142. ^^^^^^^^^^^
  143. Renders a string representation of a date.
  144. * **Input**: ``datetime.date``, ``datetime.datetime``, or a float/int timestamp
  145. * **Parameters**: the format name or pattern (optional)
  146. Assuming that ``book.pubdate`` returns a ``datetime.date`` or
  147. ``datetime.datetime`` object:
  148. .. code-block:: django
  149. {{ book.pubdate|datefmt:"short" }}
  150. would render: **4/1/07**, and
  151. .. code-block:: django
  152. {{ book.pubdate|datefmt:"E, MMM dd yyyy GGG" }}
  153. would render: **Sun, Apr 01 2007 AD**
  154. ``datetimefmt``
  155. ^^^^^^^^^^^^^^^
  156. Renders a string representation of a date and time.
  157. * **Input**: ``datetime.datetime``, or a float/int timestamp
  158. * **Parameters**: the format name or pattern (optional)
  159. Examples:
  160. .. code-block:: django
  161. {{ book.pubdate|datetimefmt:"short" }}
  162. would render: **4/1/07 3:30 PM**, and
  163. .. code-block:: django
  164. {{ book.pubdate|datetimefmt:"E, MMM dd yyyy GGG' - 'HH:mm:ss'" }}
  165. would render: **Sun, Apr 01 2007 AD - 15:30:00**
  166. ``timefmt``
  167. ^^^^^^^^^^^
  168. Renders a string representation of a time.
  169. * **Input**: ``datetime.datetime``, ``datetime.time``, or a float/int timestamp
  170. * **Parameters**: the format name or pattern (optional)
  171. Examples:
  172. .. code-block:: django
  173. {{ book.pubdate|timefmt:"short" }}
  174. would render: **3:30 PM**, and
  175. .. code-block:: django
  176. {{ book.pubdate|timefmt:"h 'o''clock' a'" }}
  177. would render: **3 o'clock PM**
  178. ``decimalfmt``
  179. ^^^^^^^^^^^^^^
  180. Renders a string representation of a decimal number.
  181. * **Input**: a `Decimal` object, or a float/int/long value
  182. * **Parameters**: the format name or pattern (optional)
  183. Examples:
  184. .. code-block:: django
  185. {{ book.pagecount|decimalfmt }}
  186. would render: **1,234**, and
  187. .. code-block:: django
  188. {{ book.pagecount|decimalfmt:"#,##0.00" }}
  189. would render: **1,234.00**
  190. ``currencyfmt``
  191. ^^^^^^^^^^^^^^^
  192. Renders a number formatted as a currency value.
  193. * **Input**: a ``Decimal`` object, or a float/int/long value
  194. * **Parameters**: the currency code
  195. Examples:
  196. .. code-block:: django
  197. {{ book.price|currencyfmt:"USD" }}
  198. would render: **$49.90**
  199. ``percentfmt``
  200. ^^^^^^^^^^^^^^
  201. Renders a string representation of a number as a percentage.
  202. * **Input**: a ``Decimal`` object, or a float/int/long value
  203. * **Parameters**: the format name or pattern (optional)
  204. Examples:
  205. Assuming ``book.rebate`` would return ``0.15``,
  206. .. code-block:: django
  207. {{ book.rebate|percentfmt }}
  208. would render **15%**, and
  209. .. code-block:: django
  210. {{ book.rebate|percentfmt:"#,##0.00%" }}
  211. would render **15.00%**.
  212. ``scientificfmt``
  213. ^^^^^^^^^^^^^^^^^
  214. Renders a string representation of a number using scientific notation.
  215. * **Input**: a ``Decimal`` object, or a float/int/long value
  216. * **Parameters**: none
  217. Examples:
  218. Assuming ``book.numsold`` would return 1.000.000,
  219. .. code-block:: django
  220. {{ book.numsold|scientificfmt }}
  221. would render **10E5**.
  222. .. _Babel: http://babel.pocoo.org/
  223. .. _Django: https://www.djangoproject.com/
  224. .. _wrapper scripts: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#localization-how-to-create-language-files
  225. .. _Distutils/Setuptools Integration: http://babel.pocoo.org/en/stable/setup.html
  226. .. _Date Formatting: http://babel.pocoo.org/en/stable/dates.html
  227. .. _Number Formatting: http://babel.pocoo.org/en/stable/numbers.html
  228. .. _Locale: http://babel.pocoo.org/en/stable/api/core.html#babel.core.Locale
  229. Changelog
  230. =========
  231. 0.6.2 (2017-12-18)
  232. ------------------
  233. - compatibility with Django 2.0 added
  234. 0.6.1 (2017-12-18)
  235. ------------------
  236. * compatibility with Django 1.11 added
  237. 0.6.0 - 2017-04-25
  238. ------------------
  239. * compatibility with unsupported Django versions (<1.8) is dropped
  240. * compatibility with Django 1.10+ middlewares was added
  241. 0.5.1 - 2016-03-30
  242. ------------------
  243. * make imports absolute in babel templatetags
  244. * strip quotes from translations via _()
  245. * fix links in docs
  246. * Add support for "trimmed" blocktrans content
  247. 0.5.0 - 2016-02-29
  248. ------------------
  249. * Add compatibility for Django-1.9
  250. 0.4.0 - 2015-04-22
  251. ------------------
  252. * Add compatibility for Django 1.8
  253. * Add compatibility for latest django master
  254. * Various python 3 fixes
  255. 0.3.9 - 2014-12-24
  256. ------------------
  257. * Fix dependencies on Django/Babel to use lower-case egg names.
  258. 0.3.8 - 2014-10-14
  259. ------------------
  260. * Fix old reference to `babeldjango` module in entry points.
  261. 0.3.7 - 2014-10-14
  262. ------------------
  263. * Fix Python 3.x compatibility in `babel makemessages` command.
  264. 0.3.6 - 2014-10-05
  265. ------------------
  266. * Django 1.7 compatibility
  267. 0.3.5 - 2014-09-10
  268. ------------------
  269. * Create .po and .pot files if not existing, plus it's specific base directories.
  270. 0.3.4 - 2014-05-25
  271. ------------------
  272. * Fixed django compatibility
  273. 0.3.3 - 2014-04-22
  274. ------------------
  275. * Fixed release builds
  276. 0.3.2 - 2014-04-22
  277. ------------------
  278. * Initial testing infrastructure
  279. * Add management command `babel` with `makemessages` and `compilemessages`
  280. labels. Mimics django's `makemessages` and `compilemessages` commands.
  281. * Various unicode fixes
  282. 0.3.1 - 2013-12-11
  283. ------------------
  284. * fix relative import in template tags
  285. 0.3.0 - 2013-12-11
  286. ------------------
  287. * Rename package to django_babel
  288. 0.2.3 - 2013-12-11
  289. ------------------
  290. * Rename package on PyPI
  291. * Use GitHub as source control
  292. .. _`master`: https://github.com/python-babel/django-babel
  293. Platform: UNKNOWN
  294. Classifier: Development Status :: 4 - Beta
  295. Classifier: Environment :: Web Environment
  296. Classifier: Intended Audience :: Developers
  297. Classifier: License :: OSI Approved :: BSD License
  298. Classifier: Operating System :: OS Independent
  299. Classifier: Programming Language :: Python
  300. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  301. Classifier: Framework :: Django
  302. Classifier: Programming Language :: Python :: 2
  303. Classifier: Programming Language :: Python :: 2.7
  304. Classifier: Programming Language :: Python :: 3
  305. Classifier: Programming Language :: Python :: 3.4
  306. Classifier: Programming Language :: Python :: 3.5
  307. Classifier: Programming Language :: Python :: 3.6
  308. Classifier: Programming Language :: Python :: Implementation :: PyPy
  309. Classifier: Programming Language :: Python :: Implementation :: CPython