Historically, Django has shipped with django.contrib.localflavor – assorted pieces of code that are useful for particular countries or cultures. Starting with Django 1.5, we’ve started the process of moving the code to outside packages (i.e., packages distributed separately from Django), for easier maintenance and to trim the size of Django’s codebase.
The localflavor packages are named django-localflavor-*, where the asterisk is an ISO 3166 country code. For example: django-localflavor-us is the localflavor package for the U.S.A.
Most of these localflavor add-ons are country-specific fields for the forms framework – for example, a USStateField that knows how to validate U.S. state abbreviations and a FISocialSecurityNumber that knows how to validate Finnish social security numbers.
To use one of these localized components, just import the relevant subpackage. For example, here’s how you can create a form with a field representing a French telephone number:
from django import forms
from django_localflavor_fr.forms import FRPhoneNumberField
class MyForm(forms.Form):
my_french_phone_no = FRPhoneNumberField()
For documentation on a given country’s localflavor helpers, see its README file.
If you’ve used the old django.contrib.localflavor package, follow these two easy steps to update your code:
Install the appropriate third-party django-localflavor-* package(s). Go to https://github.com/django/ and find the package for your country.
Change your app’s import statements to reference the new packages.
For example, change this:
from django.contrib.localflavor.fr.forms import FRPhoneNumberField
...to this:
from django_localflavor_fr.forms import FRPhoneNumberField
The code in the new packages is the same (it was copied directly from Django), so you don’t have to worry about backwards compatibility in terms of functionality. Only the imports have changed.
In Django 1.5, importing from django.contrib.localflavor will result in a DeprecationWarning. This means your code will still work, but you should change it as soon as possible.
In Django 1.6, importing from django.contrib.localflavor will no longer work.
The following countries have django-localflavor- packages.
The django.contrib.localflavor.generic package, which hasn’t been removed from Django yet, contains useful code that is not specific to one particular country or culture. Currently, it defines date, datetime and split datetime input fields based on those from forms, but with non-US default formats. Here’s an example of how to use them:
from django import forms
from django.contrib.localflavor import generic
class MyForm(forms.Form):
my_date_field = generic.forms.DateField()
Localflavor has its own catalog of translations, in the directory django/contrib/localflavor/locale, and it’s not loaded automatically like Django’s general catalog in django/conf/locale. If you want localflavor’s texts to be translated, like form fields error messages, you must include django.contrib.localflavor in the INSTALLED_APPS setting, so the internationalization system can find the catalog, as explained in How Django discovers translations.
Dec 23, 2012