149 lines
6.5 KiB
Plaintext
149 lines
6.5 KiB
Plaintext
==========================
|
|
The "local flavor" add-ons
|
|
==========================
|
|
|
|
.. module:: django.contrib.localflavor
|
|
:synopsis: A collection of various Django snippets that are useful only for
|
|
a particular country or culture.
|
|
|
|
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
|
|
:doc:`forms </topics/forms/index>` 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.
|
|
|
|
.. _ISO 3166 country code: http://www.iso.org/iso/country_codes.htm
|
|
|
|
How to migrate
|
|
==============
|
|
|
|
If you've used the old ``django.contrib.localflavor`` package, follow these two
|
|
easy steps to update your code:
|
|
|
|
1. Install the appropriate third-party ``django-localflavor-*`` package(s).
|
|
Go to https://github.com/django/ and find the package for your country.
|
|
|
|
2. 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.
|
|
|
|
Deprecation policy
|
|
==================
|
|
|
|
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.
|
|
|
|
Supported countries
|
|
===================
|
|
|
|
The following countries have django-localflavor- packages.
|
|
|
|
* Argentina: https://github.com/django/django-localflavor-ar
|
|
* Australia: https://github.com/django/django-localflavor-au
|
|
* Austria: https://github.com/django/django-localflavor-at
|
|
* Belgium: https://github.com/django/django-localflavor-be
|
|
* Brazil: https://github.com/django/django-localflavor-br
|
|
* Canada: https://github.com/django/django-localflavor-ca
|
|
* Chile: https://github.com/django/django-localflavor-cl
|
|
* China: https://github.com/django/django-localflavor-cn
|
|
* Colombia: https://github.com/django/django-localflavor-co
|
|
* Croatia: https://github.com/django/django-localflavor-cr
|
|
* Czech Republic: https://github.com/django/django-localflavor-cz
|
|
* Ecuador: https://github.com/django/django-localflavor-ec
|
|
* Finland: https://github.com/django/django-localflavor-fi
|
|
* France: https://github.com/django/django-localflavor-fr
|
|
* Germany: https://github.com/django/django-localflavor-de
|
|
* Hong Kong: https://github.com/django/django-localflavor-hk
|
|
* Iceland: https://github.com/django/django-localflavor-is
|
|
* India: https://github.com/django/django-localflavor-in
|
|
* Indonesia: https://github.com/django/django-localflavor-id
|
|
* Ireland: https://github.com/django/django-localflavor-ie
|
|
* Israel: https://github.com/django/django-localflavor-il
|
|
* Italy: https://github.com/django/django-localflavor-it
|
|
* Japan: https://github.com/django/django-localflavor-jp
|
|
* Kuwait: https://github.com/django/django-localflavor-kw
|
|
* Lithuania: https://github.com/simukis/django-localflavor-lt
|
|
* Macedonia: https://github.com/django/django-localflavor-mk
|
|
* Mexico: https://github.com/django/django-localflavor-mx
|
|
* The Netherlands: https://github.com/django/django-localflavor-nl
|
|
* Norway: https://github.com/django/django-localflavor-no
|
|
* Peru: https://github.com/django/django-localflavor-pe
|
|
* Poland: https://github.com/django/django-localflavor-pl
|
|
* Portugal: https://github.com/django/django-localflavor-pt
|
|
* Paraguay: https://github.com/django/django-localflavor-py
|
|
* Romania: https://github.com/django/django-localflavor-ro
|
|
* Russia: https://github.com/django/django-localflavor-ru
|
|
* Slovakia: https://github.com/django/django-localflavor-sk
|
|
* Slovenia: https://github.com/django/django-localflavor-si
|
|
* South Africa: https://github.com/django/django-localflavor-za
|
|
* Spain: https://github.com/django/django-localflavor-es
|
|
* Sweden: https://github.com/django/django-localflavor-se
|
|
* Switzerland: https://github.com/django/django-localflavor-ch
|
|
* Turkey: https://github.com/django/django-localflavor-tr
|
|
* United Kingdom: https://github.com/django/django-localflavor-gb
|
|
* United States of America: https://github.com/django/django-localflavor-us
|
|
* Uruguay: https://github.com/django/django-localflavor-uy
|
|
|
|
django.contrib.localflavor.generic
|
|
==================================
|
|
|
|
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 :doc:`forms </topics/forms/index>`, 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()
|
|
|
|
Internationalization of localflavor
|
|
===================================
|
|
|
|
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
|
|
:mod:`django.contrib.localflavor` in the :setting:`INSTALLED_APPS` setting, so
|
|
the internationalization system can find the catalog, as explained in
|
|
:ref:`how-django-discovers-translations`.
|