Welcome to django-babel’s documentation!¶
Tools for using Babel with Django¶
This package contains various utilities for integration of Babel into the Django web framework:
A message extraction plugin for Django templates.
A middleware class that adds the Babel Locale object to requests.
A set of template tags for date and number formatting.
Extracting Messages¶
Babel provides a message extraction framework similar to GNU xgettext
, but
more extensible and geared towards Python applications. While Django does
provide wrapper scripts for making the use of xgettext
more
convenient, the extraction functionality is rather limited. For example, you
can’t use template files with an extension other than .html
, and everything
needs to be in your project package directory.
Extraction Method Mapping¶
So django-babel comes with an extraction method plugin that can extract
localizable messages from Django template files. Python is supported out of the
box by Babel. To use this extraction functionality, create a file called
babel.cfg
in your project directory (the directory above your project
package), with the content:
[django: templates/**.*]
[django: mypkg/*/templates/**.*]
[python: mypkg/**.py]
This instructs Babel to look for any files in the top-level templates
directory, or any files in application templates
directories, and use the
extraction method named “django” to extract messages from those template files.
You’ll need to adjust those glob patterns to wherever you my be storing your
templates.
Also, any files with the extension .py
inside your package directory (replace
“mypkg” with the actual name of your Django project package) are processed by
the “python” extraction method.
If you don’t use setuptools, or for some reason haven’t installed django-babel using setuptools/pip, you’ll need to define what function the extraction method “django” maps to. This is done in an extra section at the top of the configuration file:
[extractors]
django = django_babel.extract:extract_django
The encoding of the templates is assumed to be UTF-8. If you are using a different encoding, you will need to specify it in the configuration. For example:
[django: templates/**.*]
encoding = iso-8859-1
Running the Extraction Process¶
Once you’ve set up the configuration file, the actual extraction is performed
by executing the command-line program pybabel
which is installed alongside
the Babel package:
$ cd projectdir
$ pybabel extract -F babel.cfg -o mypkg/locale/django.pot .
This creates the PO file template in mypkg/locale/django.pot
.
Creating and Updating Translations Catalogs¶
If you don’t already have translation catalogs, you need to create them. This
is done using the pybabel init
command:
$ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l en_US
$ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l de_DE
This should create two files: mypkg/locale/en_US/django.po
and
mypkg/locale/de_DE/django.po
. These files are where you put the actual
translations.
When you modify your Python source files or your templates, you genereally need
to sync the translation catalogs. For that, you first perform a fresh
extraction as described in the previous section, so that the django.pot
file
gets updated.
Then, you run the pybabel update
command to merge the changes into the
translation catalogs:
`bash
$ pybabel update -D django -i mypkg/locale/django.pot -d mypkg/locale
`
This will update all the .po
files found in the mypkg/locale
directory.
Compiling Translations Catalogs¶
Finally, you need to compile those .po
files to binary .mo
files. Use the
pybabel compile command for that:
$ pybabel compile -D django -d mypkg/locale
Add the --statistics
option to get information about the completeness of your
translations:
$ pybabel compile -D django -d mypkg/locale --statistics
Using setup.py
¶
Much of the above process can be automated if you add a setup.py
script to
your project and use the distutils/setuptools commands that come with Babel.
This is described at Distutils/Setuptools Integration.
Using the Middleware¶
To use the Babel middleware, add it to the list of MIDDLEWARE_CLASSES
in your
settings module. If you’re also using Django’s own LocaleMiddleware
to vary
the locale based on user preference, the Babel middleware must be inserted
after the Django one:
MIDDLEWARE_CLASSES = (
...
'django.middleware.locale.LocaleMiddleware',
'django_babel.middleware.LocaleMiddleware',
...
)
This adds a locale
attribute to the request object, which is an instance of
the Babel Locale
class. You can access the locale via request.locale
when
the request object is available, or otherwise use the
django_babel.middleware.get_current_locale()
function to get the current
locale from a thread-local cache.
Changelog¶
0.6.2 (2017-12-18)¶
compatibility with Django 2.0 added
0.6.1 (2017-12-18)¶
compatibility with Django 1.11 added
0.6.0 - 2017-04-25¶
compatibility with unsupported Django versions (<1.8) is dropped
compatibility with Django 1.10+ middlewares was added
0.5.1 - 2016-03-30¶
make imports absolute in babel templatetags
strip quotes from translations via _()
fix links in docs
Add support for “trimmed” blocktrans content
0.5.0 - 2016-02-29¶
Add compatibility for Django-1.9
0.4.0 - 2015-04-22¶
Add compatibility for Django 1.8
Add compatibility for latest django master
Various python 3 fixes
0.3.9 - 2014-12-24¶
Fix dependencies on Django/Babel to use lower-case egg names.
0.3.8 - 2014-10-14¶
Fix old reference to babeldjango module in entry points.
0.3.7 - 2014-10-14¶
Fix Python 3.x compatibility in babel makemessages command.
0.3.6 - 2014-10-05¶
Django 1.7 compatibility
0.3.5 - 2014-09-10¶
Create .po and .pot files if not existing, plus it’s specific base directories.
0.3.4 - 2014-05-25¶
Fixed django compatibility
0.3.3 - 2014-04-22¶
Fixed release builds
0.3.2 - 2014-04-22¶
Initial testing infrastructure
Add management command babel with makemessages and compilemessages labels. Mimics django’s makemessages and compilemessages commands.
Various unicode fixes
0.3.1 - 2013-12-11¶
fix relative import in template tags
0.3.0 - 2013-12-11¶
Rename package to django_babel
0.2.3 - 2013-12-11¶
Rename package on PyPI
Use GitHub as source control
Contents: