Sophie: python-django-doc-1.8.19-1.mga6 noarch

python-django-doc-1.8.19-1.mga6.noarch.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml" lang="">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Format localization &#8212; Django 1.8.19 documentation</title>
    
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.8.19',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="top" title="Django 1.8.19 documentation" href="../../contents.html" />
    <link rel="up" title="Internationalization and localization" href="index.html" />
    <link rel="next" title="Time zones" href="timezones.html" />
    <link rel="prev" title="Translation" href="translation.html" />



 
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body role="document">

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 1.8.19 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="translation.html" title="Translation">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="timezones.html" title="Time zones">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="topics-i18n-formatting">
            
  <div class="section" id="s-format-localization">
<span id="s-id1"></span><span id="format-localization"></span><span id="id1"></span><h1>Format localization<a class="headerlink" href="#format-localization" title="Permalink to this headline">¶</a></h1>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Django&#8217;s formatting system is capable of displaying dates, times and numbers in
templates using the format specified for the current
<a class="reference internal" href="index.html#term-locale-name"><span class="xref std std-term">locale</span></a>. It also handles localized input in forms.</p>
<p>When it&#8217;s enabled, two users accessing the same content may see dates, times and
numbers formatted in different ways, depending on the formats for their current
locale.</p>
<p>The formatting system is disabled by default. To enable it, it&#8217;s
necessary to set <a class="reference internal" href="../../ref/settings.html#std:setting-USE_L10N"><code class="xref std std-setting docutils literal"><span class="pre">USE_L10N</span> <span class="pre">=</span> <span class="pre">True</span></code></a> in your settings file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The default <code class="file docutils literal"><span class="pre">settings.py</span></code> file created by <a class="reference internal" href="../../ref/django-admin.html#django-admin-startproject"><code class="xref std std-djadmin docutils literal"><span class="pre">django-admin</span>
<span class="pre">startproject</span></code></a> includes <a class="reference internal" href="../../ref/settings.html#std:setting-USE_L10N"><code class="xref std std-setting docutils literal"><span class="pre">USE_L10N</span> <span class="pre">=</span> <span class="pre">True</span></code></a>
for convenience.  Note, however, that to enable number formatting with
thousand separators it is necessary to set <a class="reference internal" href="../../ref/settings.html#std:setting-USE_THOUSAND_SEPARATOR"><code class="xref std std-setting docutils literal"><span class="pre">USE_THOUSAND_SEPARATOR</span>
<span class="pre">=</span> <span class="pre">True</span></code></a> in your settings file. Alternatively, you
could use <a class="reference internal" href="../../ref/contrib/humanize.html#std:templatefilter-intcomma"><code class="xref std std-tfilter docutils literal"><span class="pre">intcomma</span></code></a> to format numbers in your template.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">There is also an independent but related <a class="reference internal" href="../../ref/settings.html#std:setting-USE_I18N"><code class="xref std std-setting docutils literal"><span class="pre">USE_I18N</span></code></a> setting that
controls if Django should activate translation. See
<a class="reference internal" href="translation.html"><span class="doc">Translation</span></a> for more details.</p>
</div>
</div>
<div class="section" id="s-locale-aware-input-in-forms">
<span id="locale-aware-input-in-forms"></span><h2>Locale aware input in forms<a class="headerlink" href="#locale-aware-input-in-forms" title="Permalink to this headline">¶</a></h2>
<p>When formatting is enabled, Django can use localized formats when parsing dates,
times and numbers in forms. That means it tries different formats for different
locales when guessing the format used by the user when inputting data on forms.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Django uses different formats for displaying data to those it uses for
parsing data. Most notably, the formats for parsing dates can&#8217;t use the
<code class="docutils literal"><span class="pre">%a</span></code> (abbreviated weekday name), <code class="docutils literal"><span class="pre">%A</span></code> (full weekday name),
<code class="docutils literal"><span class="pre">%b</span></code> (abbreviated month name), <code class="docutils literal"><span class="pre">%B</span></code> (full month name),
or <code class="docutils literal"><span class="pre">%p</span></code> (AM/PM).</p>
</div>
<p>To enable a form field to localize input and output data simply use its
<code class="docutils literal"><span class="pre">localize</span></code> argument:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CashRegisterForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
   <span class="n">product</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
   <span class="n">revenue</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">DecimalField</span><span class="p">(</span><span class="n">max_digits</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">decimal_places</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">localize</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-controlling-localization-in-templates">
<span id="s-topic-l10n-templates"></span><span id="controlling-localization-in-templates"></span><span id="topic-l10n-templates"></span><h2>Controlling localization in templates<a class="headerlink" href="#controlling-localization-in-templates" title="Permalink to this headline">¶</a></h2>
<p>When you have enabled formatting with <a class="reference internal" href="../../ref/settings.html#std:setting-USE_L10N"><code class="xref std std-setting docutils literal"><span class="pre">USE_L10N</span></code></a>, Django
will try to use a locale specific format whenever it outputs a value
in a template.</p>
<p>However, it may not always be appropriate to use localized values &#8211;
for example, if you&#8217;re outputting JavaScript or XML that is designed
to be machine-readable, you will always want unlocalized values. You
may also want to use localization in selected templates, rather than
using localization everywhere.</p>
<p>To allow for fine control over the use of localization, Django
provides the <code class="docutils literal"><span class="pre">l10n</span></code> template library that contains the following
tags and filters.</p>
<div class="section" id="s-template-tags">
<span id="template-tags"></span><h3>Template tags<a class="headerlink" href="#template-tags" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-localize">
<span id="s-std:templatetag-localize"></span><span id="localize"></span><span id="std:templatetag-localize"></span><h4>localize<a class="headerlink" href="#localize" title="Permalink to this headline">¶</a></h4>
<p>Enables or disables localization of template variables in the
contained block.</p>
<p>This tag allows a more fine grained control of localization than
<a class="reference internal" href="../../ref/settings.html#std:setting-USE_L10N"><code class="xref std std-setting docutils literal"><span class="pre">USE_L10N</span></code></a>.</p>
<p>To activate or deactivate localization for a template block, use:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">load</span> <span class="n">l10n</span> <span class="o">%</span><span class="p">}</span>

<span class="p">{</span><span class="o">%</span> <span class="n">localize</span> <span class="n">on</span> <span class="o">%</span><span class="p">}</span>
    <span class="p">{{</span> <span class="n">value</span> <span class="p">}}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endlocalize</span> <span class="o">%</span><span class="p">}</span>

<span class="p">{</span><span class="o">%</span> <span class="n">localize</span> <span class="n">off</span> <span class="o">%</span><span class="p">}</span>
    <span class="p">{{</span> <span class="n">value</span> <span class="p">}}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endlocalize</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The value of <a class="reference internal" href="../../ref/settings.html#std:setting-USE_L10N"><code class="xref std std-setting docutils literal"><span class="pre">USE_L10N</span></code></a> isn&#8217;t respected inside of a
<code class="docutils literal"><span class="pre">{%</span> <span class="pre">localize</span> <span class="pre">%}</span></code> block.</p>
</div>
<p>See <a class="reference internal" href="#std:templatefilter-localize"><code class="xref std std-tfilter docutils literal"><span class="pre">localize</span></code></a> and <a class="reference internal" href="#std:templatefilter-unlocalize"><code class="xref std std-tfilter docutils literal"><span class="pre">unlocalize</span></code></a> for template filters that will
do the same job on a per-variable basis.</p>
</div>
</div>
<div class="section" id="s-template-filters">
<span id="template-filters"></span><h3>Template filters<a class="headerlink" href="#template-filters" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-std:templatefilter-localize">
<span id="s-id2"></span><span id="std:templatefilter-localize"></span><span id="id2"></span><h4>localize<a class="headerlink" href="#std:templatefilter-localize" title="Permalink to this headline">¶</a></h4>
<p>Forces localization of a single value.</p>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">load</span> <span class="n">l10n</span> <span class="o">%</span><span class="p">}</span>

<span class="p">{{</span> <span class="n">value</span><span class="o">|</span><span class="n">localize</span> <span class="p">}}</span>
</pre></div>
</div>
<p>To disable localization on a single value, use <a class="reference internal" href="#std:templatefilter-unlocalize"><code class="xref std std-tfilter docutils literal"><span class="pre">unlocalize</span></code></a>. To control
localization over a large section of a template, use the <a class="reference internal" href="#std:templatetag-localize"><code class="xref std std-ttag docutils literal"><span class="pre">localize</span></code></a> template
tag.</p>
</div>
<div class="section" id="s-unlocalize">
<span id="s-std:templatefilter-unlocalize"></span><span id="unlocalize"></span><span id="std:templatefilter-unlocalize"></span><h4>unlocalize<a class="headerlink" href="#unlocalize" title="Permalink to this headline">¶</a></h4>
<p>Forces a single value to be printed without localization.</p>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">load</span> <span class="n">l10n</span> <span class="o">%</span><span class="p">}</span>

<span class="p">{{</span> <span class="n">value</span><span class="o">|</span><span class="n">unlocalize</span> <span class="p">}}</span>
</pre></div>
</div>
<p>To force localization of a single value, use <a class="reference internal" href="#std:templatefilter-localize"><code class="xref std std-tfilter docutils literal"><span class="pre">localize</span></code></a>. To
control localization over a large section of a template, use the
<a class="reference internal" href="#std:templatetag-localize"><code class="xref std std-ttag docutils literal"><span class="pre">localize</span></code></a> template tag.</p>
</div>
</div>
</div>
<div class="section" id="s-creating-custom-format-files">
<span id="s-custom-format-files"></span><span id="creating-custom-format-files"></span><span id="custom-format-files"></span><h2>Creating custom format files<a class="headerlink" href="#creating-custom-format-files" title="Permalink to this headline">¶</a></h2>
<p>Django provides format definitions for many locales, but sometimes you might
want to create your own, because a format files doesn&#8217;t exist for your locale,
or because you want to overwrite some of the values.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>The ability to specify <a class="reference internal" href="../../ref/settings.html#std:setting-FORMAT_MODULE_PATH"><code class="xref std std-setting docutils literal"><span class="pre">FORMAT_MODULE_PATH</span></code></a> as a list was added.
Previously, only a single string value was supported.</p>
</div>
<p>To use custom formats, specify the path where you&#8217;ll place format files
first. To do that, just set your <a class="reference internal" href="../../ref/settings.html#std:setting-FORMAT_MODULE_PATH"><code class="xref std std-setting docutils literal"><span class="pre">FORMAT_MODULE_PATH</span></code></a> setting to
the package where format files will exist, for instance:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FORMAT_MODULE_PATH</span> <span class="o">=</span> <span class="p">[</span>
    <span class="s1">&#39;mysite.formats&#39;</span><span class="p">,</span>
    <span class="s1">&#39;some_app.formats&#39;</span><span class="p">,</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Files are not placed directly in this directory, but in a directory named as
the locale, and must be named <code class="docutils literal"><span class="pre">formats.py</span></code>. Be careful not to put sensitive
information in these files as values inside can be exposed if you pass the
string to <code class="docutils literal"><span class="pre">django.utils.formats.get_format()</span></code> (used by the <a class="reference internal" href="../../ref/templates/builtins.html#std:templatefilter-date"><code class="xref std std-tfilter docutils literal"><span class="pre">date</span></code></a>
template filter).</p>
<p>To customize the English formats, a structure like this would be needed:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">mysite</span><span class="o">/</span>
    <span class="n">formats</span><span class="o">/</span>
        <span class="n">__init__</span><span class="o">.</span><span class="n">py</span>
        <span class="n">en</span><span class="o">/</span>
            <span class="n">__init__</span><span class="o">.</span><span class="n">py</span>
            <span class="n">formats</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>where <code class="file docutils literal"><span class="pre">formats.py</span></code> contains custom format definitions. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">unicode_literals</span>

<span class="n">THOUSAND_SEPARATOR</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="se">\xa0</span><span class="s1">&#39;</span>
</pre></div>
</div>
<p>to use a non-breaking space (Unicode <code class="docutils literal"><span class="pre">00A0</span></code>) as a thousand separator,
instead of the default for English, a comma.</p>
</div>
<div class="section" id="s-limitations-of-the-provided-locale-formats">
<span id="limitations-of-the-provided-locale-formats"></span><h2>Limitations of the provided locale formats<a class="headerlink" href="#limitations-of-the-provided-locale-formats" title="Permalink to this headline">¶</a></h2>
<p>Some locales use context-sensitive formats for numbers, which Django&#8217;s
localization system cannot handle automatically.</p>
<div class="section" id="s-switzerland-german">
<span id="switzerland-german"></span><h3>Switzerland (German)<a class="headerlink" href="#switzerland-german" title="Permalink to this headline">¶</a></h3>
<p>The Swiss number formatting depends on the type of number that is being
formatted. For monetary values, a comma is used as the thousand separator and
a decimal point for the decimal separator. For all other numbers, a comma is
used as decimal separator and a space as thousand separator. The locale format
provided by Django uses the generic separators, a comma for decimal and a space
for thousand separators.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Format localization</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#locale-aware-input-in-forms">Locale aware input in forms</a></li>
<li><a class="reference internal" href="#controlling-localization-in-templates">Controlling localization in templates</a><ul>
<li><a class="reference internal" href="#template-tags">Template tags</a><ul>
<li><a class="reference internal" href="#localize">localize</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-filters">Template filters</a><ul>
<li><a class="reference internal" href="#std:templatefilter-localize">localize</a></li>
<li><a class="reference internal" href="#unlocalize">unlocalize</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#creating-custom-format-files">Creating custom format files</a></li>
<li><a class="reference internal" href="#limitations-of-the-provided-locale-formats">Limitations of the provided locale formats</a><ul>
<li><a class="reference internal" href="#switzerland-german">Switzerland (German)</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="translation.html">Translation</a></li>
    
    
      <li>Next: <a href="timezones.html">Time zones</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../../index.html">Django 1.8.19 documentation</a>
        
          <ul><li><a href="../index.html">Using Django</a>
        
          <ul><li><a href="index.html">Internationalization and localization</a>
        
        <ul><li>Format localization</li></ul>
        </li></ul></li></ul>
      </li>
  </ul>

  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/topics/i18n/formatting.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="../../search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Mar 10, 2018</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="translation.html" title="Translation">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="timezones.html" title="Time zones">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>