mirror of https://github.com/django/django.git
116 lines
4.1 KiB
Plaintext
116 lines
4.1 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 an
|
|
external package (i.e., a package distributed separately from Django), for
|
|
easier maintenance and to trim the size of Django's codebase.
|
|
|
|
The new localflavor package is named ``django-localflavor``, with a main
|
|
module called ``localflavor`` and many subpackages using an
|
|
`ISO 3166 country code`_. For example: ``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 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
|
|
|
|
.. _localflavor-how-to-migrate:
|
|
|
|
How to migrate
|
|
==============
|
|
|
|
If you've used the old ``django.contrib.localflavor`` package or one of the
|
|
temporary ``django-localflavor-*`` releases, follow these two easy steps to
|
|
update your code:
|
|
|
|
1. Install the third-party ``django-localflavor`` package from PyPI.
|
|
|
|
2. Change your app's import statements to reference the new package.
|
|
|
|
For example, change this::
|
|
|
|
from django.contrib.localflavor.fr.forms import FRPhoneNumberField
|
|
|
|
...to this::
|
|
|
|
from localflavor.fr.forms import FRPhoneNumberField
|
|
|
|
The code in the new package 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.
|
|
|
|
.. _localflavor-deprecation-policy:
|
|
|
|
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.
|
|
|
|
.. _localflavor-packages:
|
|
|
|
Supported countries
|
|
===================
|
|
|
|
See the official documentation for more information:
|
|
|
|
https://django-localflavor.readthedocs.org/
|
|
|
|
django.contrib.localflavor.generic
|
|
==================================
|
|
|
|
The ``django.contrib.localflavor.generic`` package, which hasn't been removed from
|
|
Django 1.5 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()
|
|
|
|
Of course the same package can also be found in the ``django-localflavor``
|
|
packages and it's recommended to use that instead.
|
|
|
|
Internationalization of localflavors
|
|
====================================
|
|
|
|
To activate translations for the ``localflavor`` application, you must include
|
|
the application's name in the :setting:`INSTALLED_APPS` setting, so the
|
|
internationalization system can find the catalog, as explained in
|
|
:ref:`how-django-discovers-translations`.
|
|
|
|
If you're still using the legacy ``localflavor`` application, you must include
|
|
:mod:`django.contrib.localflavor` in :setting:`INSTALLED_APPS` (that will
|
|
raise a ``DeprecationWarning``).
|