Skip to content

Commit 258ae80

Browse files
cmlenzcmlenz
committed
Move documentation from http://babel.edgewall.org/wiki/BabelDjango to the README
1 parent 0efb826 commit 258ae80

1 file changed

Lines changed: 251 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 251 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
Tools for using Babel with Django
2-
=================================
1+
# Tools for using Babel with Django
32

43
This package contains various utilities for integration of Babel into the
54
Django web framework:
@@ -8,6 +7,254 @@ Django web framework:
87
* A middleware class that adds the Babel `Locale` object to requests.
98
* A set of template tags for date and number formatting.
109

11-
For more information please visit the wiki page for this package:
1210

13-
<http://babel.edgewall.org/wiki/BabelDjango>
11+
## Extracting Messages
12+
13+
Babel provides a message extraction framework similar to GNU `xgettext`, but more extensible and geared towards Python applications. While Django does provide [http://www.djangoproject.com/documentation/i18n/#how-to-create-language-files 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.
14+
15+
### Extraction Method Mapping
16+
17+
So !BabelDjango 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:
18+
19+
```ini
20+
[django: templates/**.*, mypkg/*/templates/**.*]
21+
[python: mypkg/**.py]
22+
```
23+
24+
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.
25+
26+
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.
27+
28+
If you don't use setuptools, or for some reason haven't installed !BabelDjango using setuptools/easy_install, 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:
29+
30+
```ini
31+
[extractors]
32+
django = babeldjango.extract:extract_django
33+
```
34+
35+
### Running the Extraction Process
36+
37+
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:
38+
39+
```bash
40+
$ cd projectdir
41+
$ pybabel extract -F babel.cfg -o mypkg/locale/django.pot .
42+
```
43+
44+
This creates the PO file template in `mypkg/locale/django.pot`.
45+
46+
### Creating and Updating Translations Catalogs
47+
48+
If you don't already have translation catalogs, you need to create them. This is done using the `pybabel init` command:
49+
50+
```bash
51+
$ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l en_US
52+
$ pybabel init -D django -i mypkg/locale/django.pot -d mypkg/locale -l de_DE
53+
```
54+
55+
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.
56+
57+
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.
58+
59+
Then, you run the `pybabel update` command to merge the changes into the translation catalogs:
60+
61+
```bash
62+
$ pybabel update -D django -i mypkg/locale/django.pot -d mypkg/locale
63+
```
64+
65+
This will update all the `.po` files found in the `mypkg/locale` directory.
66+
67+
### Compiling Translations Catalogs
68+
69+
Finally, you need to compile those `.po` files to binary `.mo` files. Use the `pybabel compile` command for that:
70+
71+
```bash
72+
$ pybabel compile -D django -d mypkg/locale
73+
```
74+
75+
Add the `--statistics` option to get information about the completeness of your translations:
76+
77+
```bash
78+
$ pybabel compile -D django -d mypkg/locale --statistics
79+
```
80+
81+
### Using `setup.py`
82+
83+
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 [wiki:Documentation/setup.html Distutils/Setuptools Integration].
84+
85+
## Using the Middleware
86+
87+
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:
88+
89+
```python
90+
MIDDLEWARE_CLASSES = (
91+
...
92+
'django.middleware.locale.LocaleMiddleware',
93+
'babeldjango.middleware.LocaleMiddleware',
94+
...
95+
)
96+
```
97+
98+
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 `babeldjango.middleware.get_current_locale()` function to get the current locale from a thread-local cache.
99+
100+
## Using the Template Tags
101+
102+
The template filters provided by !BabelDjango allow formatting of date/time and number values in a locale-sensitive manner, providing much more powerful alternatives to the `date`, `time`, and `floatformat` filters that come with Django.
103+
104+
To make the template filters/tags available, you need to add !BabelDjango to the list of `INSTALLED_APPS` in your settings module:
105+
106+
```python
107+
INSTALLED_APPS = (
108+
...
109+
'babeldjango',
110+
...
111+
)
112+
```
113+
114+
And in every template you want to use the filters, you need to explicitly load the !BabelDjango library:
115+
116+
```jinja
117+
{% load babel %}
118+
```
119+
120+
General information on date/time and number formatting can be found at [wiki:Documentation/dates.html Date Formatting] and [wiki:Documentation/numbers.html Number Formatting].
121+
122+
The following filters are made available. The examples assume a locale of `en_US`.
123+
124+
### `datefmt`
125+
126+
Renders a string representation of a date.
127+
128+
* __Input__: `datetime.date`, `datetime.datetime`, or a float/int timestamp
129+
* __Parameters__: the format name or pattern (optional)
130+
131+
Assuming that `book.pubdate` returns a `datetime.date` or `datetime.datetime` object:
132+
133+
```jinja
134+
{{ book.pubdate|datefmt:"short" }}
135+
```
136+
137+
would render: **4/1/07**, and
138+
139+
```jinja
140+
{{ book.pubdate|datefmt:"E, MMM dd yyyy GGG" }}
141+
```
142+
143+
would render: **Sun, Apr 01 2007 AD**
144+
145+
### `datetimefmt`
146+
147+
Renders a string representation of a date and time.
148+
149+
* __Input__: `datetime.datetime`, or a float/int timestamp
150+
* __Parameters__: the format name or pattern (optional)
151+
152+
Examples:
153+
```jinja
154+
{{ book.pubdate|datetimefmt:"short" }}
155+
```
156+
157+
would render: **4/1/07 3:30 PM**, and
158+
159+
```jinja
160+
{{ book.pubdate|datetimefmt:"E, MMM dd yyyy GGG' - 'HH:mm:ss'" }}
161+
```
162+
163+
would render: **Sun, Apr 01 2007 AD - 15:30:00**
164+
165+
### `timefmt`
166+
167+
Renders a string representation of a time.
168+
169+
* __Input__: `datetime.datetime`, `datetime.time`, or a float/int timestamp
170+
* __Parameters__: the format name or pattern (optional)
171+
172+
Examples:
173+
174+
```jinja
175+
{{ book.pubdate|timefmt:"short" }}
176+
```
177+
178+
would render: **3:30 PM**, and
179+
180+
```jinja
181+
{{ book.pubdate|timefmt:"h 'o''clock' a'" }}
182+
```
183+
184+
would render: **3 o'clock PM**
185+
186+
### `decimalfmt`
187+
188+
Renders a string representation of a decimal number.
189+
190+
* __Input__: a `Decimal` object, or a float/int/long value
191+
* __Parameters__: the format name or pattern (optional)
192+
193+
Examples:
194+
195+
```jinja
196+
{{ book.pagecount|decimalfmt }}
197+
```
198+
199+
would render: **1,234**, and
200+
201+
```jinja
202+
{{ book.pagecount|decimalfmt:"#,##0.00" }}
203+
```
204+
205+
would render: **1,234.00**
206+
207+
### `currencyfmt`
208+
209+
Renders a number formatted as a currency value.
210+
211+
* __Input__: a `Decimal` object, or a float/int/long value
212+
* __Parameters__: the currency code
213+
214+
Examples:
215+
216+
```jinja
217+
{{ book.price|currencyfmt:"USD" }}
218+
```
219+
220+
would render: **$49.90**
221+
222+
### `percentfmt`
223+
224+
Renders a string representation of a number as a percentage.
225+
226+
* __Input__: a `Decimal` object, or a float/int/long value
227+
* __Parameters__: the format name or pattern (optional)
228+
229+
Examples:
230+
231+
Assuming `book.rebate` would return `0.15`,
232+
233+
```jinja
234+
{{ book.rebate|percentfmt }}
235+
```
236+
237+
would render **15%**, and
238+
239+
```jinja
240+
{{ book.rebate|percentfmt:"#,##0.00%" }}
241+
```
242+
243+
would render **15.00%**.
244+
245+
### `scientificfmt`
246+
247+
Renders a string representation of a number using scientific notation.
248+
249+
* __Input__: a `Decimal` object, or a float/int/long value
250+
* __Parameters__: none
251+
252+
Examples:
253+
254+
Assuming `book.numsold` would return 1.000.000,
255+
256+
```jinja
257+
{{ book.numsold|scientificfmt }}
258+
```
259+
260+
would render **10E5**.

0 commit comments

Comments
 (0)