Debian Codegraph @

docs/topics/i18n/formatting.txt

raw
1 ===================
2 Format localization
3 ===================
4
5 Overview
6 ========
7
8 Django's formatting system is capable of displaying dates, times and numbers in
9 templates using the format specified for the current
10 :term:`locale <locale name>`. It also handles localized input in forms.
11
12 Two users accessing the same content may see dates, times and numbers formatted
13 in different ways, depending on the formats for their current locale.
14
15 .. note::
16
17 To enable number formatting with thousand separators, it is necessary to
18 set :setting:`USE_THOUSAND_SEPARATOR = True <USE_THOUSAND_SEPARATOR>` in
19 your settings file. Alternatively, you could use :tfilter:`intcomma` to
20 format numbers in your template.
21
22 .. note::
23
24 There is a related :setting:`USE_I18N` setting that controls if Django
25 should activate translation. See :doc:`/topics/i18n/translation` for more
26 details.
27
28 Locale aware input in forms
29 ===========================
30
31 When formatting is enabled, Django can use localized formats when parsing dates,
32 times and numbers in forms. That means it tries different formats for different
33 locales when guessing the format used by the user when inputting data on forms.
34
35 .. note::
36 Django uses different formats for displaying data to those it uses for
37 parsing data. Most notably, the formats for parsing dates can't use the
38 ``%a`` (abbreviated weekday name), ``%A`` (full weekday name),
39 ``%b`` (abbreviated month name), ``%B`` (full month name),
40 or ``%p`` (AM/PM).
41
42 To enable a form field to localize input and output data use its ``localize``
43 argument::
44
45 class CashRegisterForm(forms.Form):
46 product = forms.CharField()
47 revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)
48
49 .. _topic-l10n-templates:
50
51 Controlling localization in templates
52 =====================================
53
54 Django tries to use a locale specific format whenever it outputs a value in a
55 template.
56
57 However, it may not always be appropriate to use localized values --
58 for example, if you're outputting JavaScript or XML that is designed
59 to be machine-readable, you will always want unlocalized values. You
60 may also want to use localization in selected templates, rather than
61 using localization everywhere.
62
63 To allow for fine control over the use of localization, Django
64 provides the ``l10n`` template library that contains the following
65 tags and filters.
66
67 Template tags
68 -------------
69
70 .. templatetag:: localize
71
72 ``localize``
73 ~~~~~~~~~~~~
74
75 Enables or disables localization of template variables in the
76 contained block.
77
78 To activate or deactivate localization for a template block, use:
79
80 .. code-block:: html+django
81
82 {% load l10n %}
83
84 {% localize on %}
85 {{ value }}
86 {% endlocalize %}
87
88 {% localize off %}
89 {{ value }}
90 {% endlocalize %}
91
92 When localization is disabled, the :ref:`localization settings <settings-l10n>`
93 formats are applied.
94
95 See :tfilter:`localize` and :tfilter:`unlocalize` for template filters that will
96 do the same job on a per-variable basis.
97
98 Template filters
99 ----------------
100
101 .. templatefilter:: localize
102
103 ``localize``
104 ~~~~~~~~~~~~
105
106 Forces localization of a single value.
107
108 For example:
109
110 .. code-block:: html+django
111
112 {% load l10n %}
113
114 {{ value|localize }}
115
116 To disable localization on a single value, use :tfilter:`unlocalize`. To control
117 localization over a large section of a template, use the :ttag:`localize` template
118 tag.
119
120 .. templatefilter:: unlocalize
121
122 ``unlocalize``
123 ~~~~~~~~~~~~~~
124
125 Forces a single value to be printed without localization.
126
127 For example:
128
129 .. code-block:: html+django
130
131 {% load l10n %}
132
133 {{ value|unlocalize }}
134
135 To force localization of a single value, use :tfilter:`localize`. To
136 control localization over a large section of a template, use the
137 :ttag:`localize` template tag.
138
139 Returns a string representation for numbers (``int``, ``float``, or
140 ``Decimal``) with the :ref:`localization settings <settings-l10n>` formats
141 applied.
142
143 .. _custom-format-files:
144
145 Creating custom format files
146 ============================
147
148 Django provides format definitions for many locales, but sometimes you might
149 want to create your own, because a format file doesn't exist for your locale,
150 or because you want to overwrite some of the values.
151
152 To use custom formats, specify the path where you'll place format files
153 first. To do that, set your :setting:`FORMAT_MODULE_PATH` setting to the
154 package where format files will exist, for instance::
155
156 FORMAT_MODULE_PATH = [
157 "mysite.formats",
158 "some_app.formats",
159 ]
160
161 Files are not placed directly in this directory, but in a directory named as
162 the locale, and must be named ``formats.py``. Be careful not to put sensitive
163 information in these files as values inside can be exposed if you pass the
164 string to ``django.utils.formats.get_format()`` (used by the :tfilter:`date`
165 template filter).
166
167 To customize the English formats, a structure like this would be needed:
168
169 .. code-block:: text
170
171 mysite/
172 formats/
173 __init__.py
174 en/
175 __init__.py
176 formats.py
177
178 where :file:`formats.py` contains custom format definitions. For example::
179
180 THOUSAND_SEPARATOR = "\xa0"
181
182 to use a non-breaking space (Unicode ``00A0``) as a thousand separator,
183 instead of the default for English, a comma.
184
185 Limitations of the provided locale formats
186 ==========================================
187
188 Some locales use context-sensitive formats for numbers, which Django's
189 localization system cannot handle automatically.
190
191 Switzerland (German, French)
192 ----------------------------
193
194 The Swiss number formatting traditionally varies depending on context. For
195 example, monetary values may use a dot as decimal separator (``Fr. 23.50``),
196 while measurements often use a comma (``22,5 m``). Django’s localization system
197 does not support such context-specific variations automatically.
198
199 The locale format provided by Django uses the generic separators, a comma for
200 decimal and a space for thousand separators.