# Django 3.2.11.dev 文档

# 本地格式化

## 概况

Django 的格式化系统可以在模板中使用指定的格式化工具为当前的 locale 来显示日期、时间和数字。

启用后，访问相同内容的两个用户可能看见不同的日期、时间和数字，这取决于他们本地的语言环境。

格式化系统默认是关闭的。如果要启用它，在配置文件里设置 `USE_L10N = True` 即可。

注解

方便起见，`django-admin startproject 1` 创建 `settings.py` 文件，包含 `USE_L10N = True` 的 。注意，启用千分位的数字格式化需要在配置文件里设置 `USE_THOUSAND_SEPARATOR = True` 。或者，在模板里可以使用 `intcomma` 来格式化数字。

注解

还有一个有关 `USE_I18N` 的设置，用来控制 Django 是否可以动态翻译。查看 翻译 获取更多细节。

## 表单中感知本地语言环境输入

格式化开启后，当在表单里解析日期、时间和数字时，Django 可以使用本地化格式。这意味着猜测用户在表单上的输入时所使用的格式化时，会对不同语言环境尝试不同的格式化。

注解

Django 使用与解析数据不同的格式来显示数据。最值得注意的是，解析日期的格式化不能使用 `%a` （缩写的日期），`%A` （完整的日期），`%b` （缩写的月份），`%B` （完整的月份），或者 `%p` (AM/PM)。

使用 `localize` 参数来使表单字段能本地化输入和输出数据：

    class CashRegisterForm(forms.Form):
       product = forms.CharField()
       revenue = forms.DecimalField(max_digits=4, decimal_places=2, localize=True)

## 在模板中控制本地化

使用 `USE_L10N` 启用格式化后，每当 Django 在模板中输入数值时，它会试着使用本地语言环境指定的格式化。

然而，使用本地化值可能并不总是合适的——比如，如果你正在输出机器可读的 JavaScript 或 XML ，则始终需要非本地化的值。你也可以在已选的模板里使用本地化，而不是在所有地方使用。

为了更好的控制本地化的使用，Django 提供 `l10n` 模板库，它包含以下的 tags 和 filters。

### 模板标签

#### `localize`

在模板里启用和禁用模板变量本地化。

相比 `USE_L10N` ，这个标签可对本地化进行更精细的控制。

要为模板块激活或禁用本地化，请用：

    {% load l10n %}

    {% localize on %}
        {{ value }}
    {% endlocalize %}

    {% localize off %}
        {{ value }}
    {% endlocalize %}

注解

在 `{% localize %}` 块中，`USE_L10N` 的值会被忽略。

查看 `localize` 和 `unlocalize` 来获取在每个变量基础上执行相同任务的模板过滤器。

### 模板过滤器

#### `localize`

对单一值的强制本地化

例如:

    {% load l10n %}

    {{ value|localize }}

对单一值取消本地化，使用 `unlocalize` 。要控制大部分模板的本地化，请使用 `localize` 模板标签。

#### `unlocalize`

强制地让单一值不被本地化。

例如:

    {% load l10n %}

    {{ value|unlocalize }}

对单一值强制本地化，使用 `localize` 。要控制大部分模板的本地化，请使用 `localize` 模板标签。

返回未本地化数字（`int`、`float` 或 `Decimal`）的字符串表示。

## 创建自定义的格式化文件

Django provides format definitions for many locales, but sometimes you might want to create your own, because a format file doesn't exist for your locale, or because you want to overwrite some of the values.

要使用自定义格式化，你首先要指定格式化文件的路径，需要将 `FORMAT_MODULE_PATH` 设置为格式化文件所在的包路径，例如：

    FORMAT_MODULE_PATH = [
        'mysite.formats',
        'some_app.formats',
    ]

文件不能直接放置在这个目录里，而是要放在本地语言环境的目录中，而且必须命名为 `formats.py` 。要注意不要在这些文件里放置敏感信息，因为如果你把字符串传递给 `django.utils.formats.get_format()` （使用 `date` 模板过滤器），那么内部值会被暴露。

要想自定义英语格式化，需要这样的结构：

    mysite/
        formats/
            __init__.py
            en/
                __init__.py
                formats.py

`formats.py` 包含自定义格式化定义。例如：

    THOUSAND_SEPARATOR = '\xa0'

使用不换行空格（硬空格 Unicode `00A0` ）作为千位分隔符，而不是英语的默认逗号。

## 提供本地语言环境格式化的局限性

一些本地语言环境为数字使用上下文相关的格式化，而 Django 本地化系统不能自动处理。

### Switzerland (German)

瑞士数字格式化取决于要格式化的数字类型。对于货币值，用逗号作为千位分隔符，小数点作为小数点分隔符。对于其他数字，逗号用作小数点分隔符，空格用作千分位分隔符。Django 提供的本地语言环境格式化使用通用分隔符，小数点用逗号，千分位分隔符用空格。