django1/docs/ref/contrib/localflavor.txt

==========================
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`.