{"title":"本地格式化","version":"4.0","locale":"zh-hans","docname":"topics/i18n/formatting","url":"/zh-hans/4.0/topics/i18n/formatting/","canonical":"https://djangodocs.dev/zh-hans/4.0/topics/i18n/formatting/","summary":"概况 Link to this heading # Django 的格式化系统可以在模板中使用指定的格式化工具为当前的 locale 来显示日期、时间和数字。 启用后，访问相同内容的两个用户可能看见不同的日期、时间和数字，这取决于他们本地的语言环境。 格式化系统默认是关闭的。如果要启用它，在配置文件里设置 USE_L10N =…","html":"<h1>本地格式化<a class=\"heading-anchor\" href=\"#format-localization\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h1>\n<section id=\"overview\">\n<h2>概况<a class=\"heading-anchor\" href=\"#overview\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>Django 的格式化系统可以在模板中使用指定的格式化工具为当前的 <a class=\"reference internal\" href=\"/zh-hans/4.0/topics/i18n/#term-locale-name\"><span class=\"xref std std-term\">locale</span></a> 来显示日期、时间和数字。</p>\n<p>启用后，访问相同内容的两个用户可能看见不同的日期、时间和数字，这取决于他们本地的语言环境。</p>\n<p>格式化系统默认是关闭的。如果要启用它，在配置文件里设置 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_L10N\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_L10N</span> <span class=\"pre\">=</span> <span class=\"pre\">True</span></code></a> 即可。</p>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>要启用千位分隔符的数字格式，必须在你的配置文件中设置 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_THOUSAND_SEPARATOR\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_THOUSAND_SEPARATOR</span> <span class=\"pre\">=</span> <span class=\"pre\">True</span></code></a>。另外，你可以使用 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/contrib/humanize/#std-templatefilter-intcomma\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">intcomma</span></code></a> 在你的模板中格式化数字。</p>\n</aside>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>有一个相关的 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_I18N\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_I18N</span></code></a> 配置，控制 Django 是否应该激活翻译。更多细节请参见 <a class=\"reference internal\" href=\"/zh-hans/4.0/topics/i18n/translation/\"><span class=\"doc\">翻译</span></a>。</p>\n</aside>\n</section>\n<section id=\"locale-aware-input-in-forms\">\n<h2>表单中感知本地语言环境输入<a class=\"heading-anchor\" href=\"#locale-aware-input-in-forms\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>格式化开启后，当在表单里解析日期、时间和数字时，Django 可以使用本地化格式。这意味着猜测用户在表单上的输入时所使用的格式化时，会对不同语言环境尝试不同的格式化。</p>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>Django 使用与解析数据不同的格式来显示数据。最值得注意的是，解析日期的格式化不能使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">%a</span></code> （缩写的日期），<code class=\"docutils literal notranslate\"><span class=\"pre\">%A</span></code> （完整的日期），<code class=\"docutils literal notranslate\"><span class=\"pre\">%b</span></code> （缩写的月份），<code class=\"docutils literal notranslate\"><span class=\"pre\">%B</span></code> （完整的月份），或者 <code class=\"docutils literal notranslate\"><span class=\"pre\">%p</span></code> (AM/PM)。</p>\n</aside>\n<p>使用 <code class=\"docutils literal notranslate\"><span class=\"pre\">localize</span></code> 参数来使表单字段能本地化输入和输出数据：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"k\">class</span><span class=\"w\"> </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>\n   <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>\n   <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>\n</code></pre></div>\n</section>\n<section id=\"controlling-localization-in-templates\">\n<span id=\"topic-l10n-templates\"></span><h2>在模板中控制本地化<a class=\"heading-anchor\" href=\"#controlling-localization-in-templates\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>使用 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_L10N\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_L10N</span></code></a> 启用格式化后，每当 Django 在模板中输入数值时，它会试着使用本地语言环境指定的格式化。</p>\n<p>然而，使用本地化值可能并不总是合适的——比如，如果你正在输出机器可读的 JavaScript 或 XML ，则始终需要非本地化的值。你也可以在已选的模板里使用本地化，而不是在所有地方使用。</p>\n<p>为了更好的控制本地化的使用，Django 提供 <code class=\"docutils literal notranslate\"><span class=\"pre\">l10n</span></code> 模板库，它包含以下的  tags 和 filters。</p>\n<section id=\"template-tags\">\n<h3>模板标签<a class=\"heading-anchor\" href=\"#template-tags\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<section id=\"localize\">\n<span id=\"std-templatetag-localize\"></span><h4><code class=\"docutils literal notranslate\"><span class=\"pre\">localize</span></code><a class=\"heading-anchor\" href=\"#localize\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h4>\n<p>在模板里启用和禁用模板变量本地化。</p>\n<p>相比 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_L10N\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_L10N</span></code></a> ，这个标签可对本地化进行更精细的控制。</p>\n<p>要为模板块激活或禁用本地化，请用：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><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>\n\n<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>\n    <span class=\"p\">{{</span> <span class=\"n\">value</span> <span class=\"p\">}}</span>\n<span class=\"p\">{</span><span class=\"o\">%</span> <span class=\"n\">endlocalize</span> <span class=\"o\">%</span><span class=\"p\">}</span>\n\n<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>\n    <span class=\"p\">{{</span> <span class=\"n\">value</span> <span class=\"p\">}}</span>\n<span class=\"p\">{</span><span class=\"o\">%</span> <span class=\"n\">endlocalize</span> <span class=\"o\">%</span><span class=\"p\">}</span>\n</code></pre></div>\n<aside class=\"admonition admonition-note\" role=\"note\">\n<p class=\"admonition-title\">Note</p>\n<p>在 <code class=\"docutils literal notranslate\"><span class=\"pre\">{%</span> <span class=\"pre\">localize</span> <span class=\"pre\">%}</span></code> 块中，<a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-USE_L10N\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">USE_L10N</span></code></a> 的值会被忽略。</p>\n</aside>\n<p>查看 <a class=\"reference internal\" href=\"#std-templatefilter-localize\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">localize</span></code></a> 和 <a class=\"reference internal\" href=\"#std-templatefilter-unlocalize\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">unlocalize</span></code></a> 来获取在每个变量基础上执行相同任务的模板过滤器。</p>\n</section>\n</section>\n<section id=\"template-filters\">\n<h3>模板过滤器<a class=\"heading-anchor\" href=\"#template-filters\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<section id=\"std-templatefilter-localize\">\n<span id=\"id1\"></span><h4><code class=\"docutils literal notranslate\"><span class=\"pre\">localize</span></code><a class=\"heading-anchor\" href=\"#std-templatefilter-localize\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h4>\n<p>对单一值的强制本地化</p>\n<p>例如：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><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>\n\n<span class=\"p\">{{</span> <span class=\"n\">value</span><span class=\"o\">|</span><span class=\"n\">localize</span> <span class=\"p\">}}</span>\n</code></pre></div>\n<p>对单一值取消本地化，使用 <a class=\"reference internal\" href=\"#std-templatefilter-unlocalize\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">unlocalize</span></code></a> 。要控制大部分模板的本地化，请使用 <a class=\"reference internal\" href=\"#std-templatetag-localize\"><code class=\"xref std std-ttag docutils literal notranslate\"><span class=\"pre\">localize</span></code></a> 模板标签。</p>\n</section>\n<section id=\"unlocalize\">\n<span id=\"std-templatefilter-unlocalize\"></span><h4><code class=\"docutils literal notranslate\"><span class=\"pre\">unlocalize</span></code><a class=\"heading-anchor\" href=\"#unlocalize\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h4>\n<p>强制地让单一值不被本地化。</p>\n<p>例如：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><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>\n\n<span class=\"p\">{{</span> <span class=\"n\">value</span><span class=\"o\">|</span><span class=\"n\">unlocalize</span> <span class=\"p\">}}</span>\n</code></pre></div>\n<p>对单一值强制本地化，使用 <a class=\"reference internal\" href=\"#std-templatefilter-localize\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">localize</span></code></a> 。要控制大部分模板的本地化，请使用 <a class=\"reference internal\" href=\"#std-templatetag-localize\"><code class=\"xref std std-ttag docutils literal notranslate\"><span class=\"pre\">localize</span></code></a> 模板标签。</p>\n<p>返回未本地化数字（<code class=\"docutils literal notranslate\"><span class=\"pre\">int</span></code>、<code class=\"docutils literal notranslate\"><span class=\"pre\">float</span></code> 或 <code class=\"docutils literal notranslate\"><span class=\"pre\">Decimal</span></code>）的字符串表示。</p>\n</section>\n</section>\n</section>\n<section id=\"creating-custom-format-files\">\n<span id=\"custom-format-files\"></span><h2>创建自定义的格式化文件<a class=\"heading-anchor\" href=\"#creating-custom-format-files\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>Django 为许多地区提供了格式定义，但有时你可能想创建自己的格式，因为你的地区不存在一个格式文件，或者你想覆盖一些值。</p>\n<p>要使用自定义格式化，你首先要指定格式化文件的路径，需要将 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/settings/#std-setting-FORMAT_MODULE_PATH\"><code class=\"xref std std-setting docutils literal notranslate\"><span class=\"pre\">FORMAT_MODULE_PATH</span></code></a> 设置为格式化文件所在的包路径，例如：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">FORMAT_MODULE_PATH</span> <span class=\"o\">=</span> <span class=\"p\">[</span>\n    <span class=\"s1\">&#39;mysite.formats&#39;</span><span class=\"p\">,</span>\n    <span class=\"s1\">&#39;some_app.formats&#39;</span><span class=\"p\">,</span>\n<span class=\"p\">]</span>\n</code></pre></div>\n<p>文件不能直接放置在这个目录里，而是要放在本地语言环境的目录中，而且必须命名为 <code class=\"docutils literal notranslate\"><span class=\"pre\">formats.py</span></code> 。要注意不要在这些文件里放置敏感信息，因为如果你把字符串传递给 <code class=\"docutils literal notranslate\"><span class=\"pre\">django.utils.formats.get_format()</span></code> （使用 <a class=\"reference internal\" href=\"/zh-hans/4.0/ref/templates/builtins/#std-templatefilter-date\"><code class=\"xref std std-tfilter docutils literal notranslate\"><span class=\"pre\">date</span></code></a> 模板过滤器），那么内部值会被暴露。</p>\n<p>要想自定义英语格式化，需要这样的结构：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><span class=\"n\">mysite</span><span class=\"o\">/</span>\n    <span class=\"n\">formats</span><span class=\"o\">/</span>\n        <span class=\"fm\">__init__</span><span class=\"o\">.</span><span class=\"n\">py</span>\n        <span class=\"n\">en</span><span class=\"o\">/</span>\n            <span class=\"fm\">__init__</span><span class=\"o\">.</span><span class=\"n\">py</span>\n            <span class=\"n\">formats</span><span class=\"o\">.</span><span class=\"n\">py</span>\n</code></pre></div>\n<p><code class=\"file docutils literal notranslate\"><span class=\"pre\">formats.py</span></code> 包含自定义格式化定义。例如：</p>\n<div class=\"code-block\" data-language=\"default\"><div class=\"code-block-toolbar\"><span class=\"code-block-language\">Code</span><button type=\"button\" class=\"copy-button\" data-copy hidden><span class=\"copy-button-label\">Copy</span></button></div><pre role=\"group\" tabindex=\"0\" aria-label=\"Code code\"><code><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>\n</code></pre></div>\n<p>使用不换行空格（硬空格 Unicode <code class=\"docutils literal notranslate\"><span class=\"pre\">00A0</span></code> ）作为千位分隔符，而不是英语的默认逗号。</p>\n</section>\n<section id=\"limitations-of-the-provided-locale-formats\">\n<h2>提供本地语言环境格式化的局限性<a class=\"heading-anchor\" href=\"#limitations-of-the-provided-locale-formats\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h2>\n<p>一些本地语言环境为数字使用上下文相关的格式化，而 Django 本地化系统不能自动处理。</p>\n<section id=\"switzerland-german\">\n<h3>Switzerland (German)<a class=\"heading-anchor\" href=\"#switzerland-german\"><span class=\"visually-hidden\">Link to this heading</span><span aria-hidden=\"true\">#</span></a></h3>\n<p>瑞士数字格式化取决于要格式化的数字类型。对于货币值，用逗号作为千位分隔符，小数点作为小数点分隔符。对于其他数字，逗号用作小数点分隔符，空格用作千分位分隔符。Django 提供的本地语言环境格式化使用通用分隔符，小数点用逗号，千分位分隔符用空格。</p>\n</section>\n</section>","rootId":"format-localization","toc":[{"title":"概况","anchor":"overview","children":[]},{"title":"表单中感知本地语言环境输入","anchor":"locale-aware-input-in-forms","children":[]},{"title":"在模板中控制本地化","anchor":"controlling-localization-in-templates","children":[{"title":"模板标签","anchor":"template-tags","children":[{"title":"localize","anchor":"localize","children":[]}]},{"title":"模板过滤器","anchor":"template-filters","children":[{"title":"localize","anchor":"std-templatefilter-localize","children":[]},{"title":"unlocalize","anchor":"unlocalize","children":[]}]}]},{"title":"创建自定义的格式化文件","anchor":"creating-custom-format-files","children":[]},{"title":"提供本地语言环境格式化的局限性","anchor":"limitations-of-the-provided-locale-formats","children":[{"title":"Switzerland (German)","anchor":"switzerland-german","children":[]}]}],"breadcrumbs":[{"docname":"topics/index","title":"使用 Django","url":"/zh-hans/4.0/topics/"},{"docname":"topics/i18n/index","title":"国际化和本地化","url":"/zh-hans/4.0/topics/i18n/"}],"prev":{"docname":"topics/i18n/translation","title":"翻译","url":"/zh-hans/4.0/topics/i18n/translation/"},"next":{"docname":"topics/i18n/timezones","title":"时区","url":"/zh-hans/4.0/topics/i18n/timezones/"},"formats":{"html":"/zh-hans/4.0/topics/i18n/formatting/","markdown":"/zh-hans/4.0/topics/i18n/formatting.md","json":"/zh-hans/4.0/topics/i18n/formatting.json"},"source":"https://github.com/django/django/blob/stable/4.0.x/docs/topics/i18n/formatting.txt","official":"https://docs.djangoproject.com/zh-hans/4.0/topics/i18n/formatting/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}