Skip to content

5. 国际化

国际化的应用程序以用户的语言显示其文本。案例研究使用法语和英语。原理很简单:模板包含标记为“待翻译”的文本,每种语言有一个词典,将每段文本与其译文相关联。所选的语言存储在 Cookie 中。

[Django] 为此使用 [gettext],这是 GNU 项目的翻译系统,[Python] 也支持它(标准库中的 [gettext] 模块),许多开源软件中都能见到它。使用 [gettext] 时,文本的键就是文本本身,以原始语言书写:模板中写成 [{% translate "Home" %}],而法语词典将“Home”与“Accueil”关联起来。因此,即使没有词典,页面仍然可读且可用:文本以原始语言显示。这与 [Symfony]、[Laravel]、[Flask]、[Spring MVC]、[ASP.NET Core MVC] 和 [NestJS] 课程中的 案例研究版本不同,后者使用抽象键([MENU.HOME])。词典是 [.po] (Portable Object)格式的文本文件,工具可以从代码中提取它们,翻译软件可以编辑它们;[Django] 读取的是其编译版本,即 [.mo] (Machine Object)文件。[gettext] 还可以根据每种语言的规则将文本变为复数形式。[Django] 本身就是以这种方式翻译的:正是借助其词典,它才能以法语显示错误消息(自示例 08 起,错误消息一直是英文,即默认语言)。日期和金额的格式与示例 16 中保持一致。

5.1. 示例 22:双语应用程序

22-i18n/
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── locale/
│   └── fr/
│       └── LC_MESSAGES/
│           ├── django.mo
│           └── django.po
├── pages/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── formats.py
│   ├── __init__.py
│   ├── viewmodels.py
│   └── views.py
├── static/
│   └── ...
├── templates/
│   ├── fragments/
│   │   └── navbar.html
│   ├── pages/
│   │   ├── home.html
│   │   └── products.html
│   └── layout.html
└── manage.py

5.1.1. 配置:config/settings.py

# config/settings.py:示例 22 的配置

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-e%uqntr!nz5i2w(d^_-cwr6w=w^2z^mx6vpvpgsg91qvp)bnzl"
ALLOWED_HOSTS = []
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# 默认语言,以及应用处理的语言
LANGUAGE_CODE = "en"
LANGUAGES = [
    ("fr", "Français"),
    ("en", "English"),
]
# 应用词典的文件夹(.po 文件,编译为 .mo)
LOCALE_PATHS = [BASE_DIR / "locale"]
# 记住所选语言的 Cookie(这也是默认名称)
LANGUAGE_COOKIE_NAME = "django_language"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "pages",
]

MIDDLEWARE = [
    # LocaleMiddleware:每个请求的语言,先从语言 Cookie 中读取,
    # 没有则从浏览器的 Accept-Language 头部读取,再没有则使用 LANGUAGE_CODE
    "django.middleware.locale.LocaleMiddleware",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                # LANGUAGE_CODE 变量:请求的语言
                "django.template.context_processors.i18n",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • 第 14 行:应用程序的默认语言,用于未指定语言的请求(示例 08)。这也是模板文本所使用的语言;因此,英语不需要词典;
  • 第 15–18 行:应用程序支持的语言;
  • 第 20 行:[LOCALE_PATHS],[Django] 查找应用程序词典的文件夹,此外还会查找每个应用的 [locale] 文件夹(包括 [Django] 自身的文件夹)。每个词典存放在 [<language>/LC_MESSAGES] 文件夹中,名称为 [django.po] (以及 [django.mo]):这是 [gettext] 所要求的组织方式;
  • 第 22 行:存储所选语言的 Cookie 的名称。[django_language] 是默认值;我们在此写出以便可见;
  • 第 29–33 行:来自 [LocaleMiddleware] 的 [Django] 中间件取代了示例 16 中我们自己的 [SetLanguage] 中间件。对于每个请求,它从 [LANGUAGES] 设置中指定的语言里选择语言:如果存在语言 Cookie,则使用其中指定的语言;否则,根据 [Accept-Language] 头部(示例 12)使用浏览器的首选语言;再否则,使用 [LANGUAGE_CODE]。它激活该语言([translation.activate],示例 16),并将其存储在 [request.LANGUAGE_CODE] 中。最后,它在响应中添加头部 [Content-Language] (页面的语言),以及头部 [Vary: Accept-Language],后者通知缓存响应取决于此头部;
  • 第 43 行:上下文处理器 [i18n] 向模板添加变量 [LANGUAGE_CODE] (请求的语言)、[LANGUAGES] 和 [LANGUAGE_BIDI] (对于从右向左书写的语言为真)。

5.1.2. 词典:locale/fr/LC_MESSAGES/django.po

# locale/fr/LC_MESSAGES/django.po:示例 22 的法语词典。
# msgid:原文,与其在模板中的写法一致(英语);
# msgstr:其译文。该文件通过以下命令编译为 django.mo(Django
# 读取的文件):python manage.py compilemessages
msgid ""
msgstr ""
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"

#: templates/fragments/navbar.html:6
msgid "Home"
msgstr "Accueil"

#: templates/fragments/navbar.html:7
msgid "Products"
msgstr "Produits"

#: templates/pages/home.html:4 templates/pages/home.html:7
msgid "Welcome"
msgstr "Bienvenue"

#: templates/pages/home.html:9
#, python-format
msgid "Hello %(name)s!"
msgstr "Bonjour %(name)s !"

#: templates/pages/home.html:11
#, python-format
msgid "Today is %(date)s."
msgstr "Nous sommes le %(date)s."

#: templates/pages/products.html:4 templates/pages/products.html:7
msgid "Our products"
msgstr "Nos produits"

#: templates/pages/products.html:9
msgid "Product"
msgstr "Produit"

#: templates/pages/products.html:9
msgid "Price"
msgstr "Prix"

#: templates/pages/products.html:21
#, python-format
msgid "%(n)s product in the catalogue."
msgid_plural "%(n)s products in the catalogue."
msgstr[0] "%(n)s produit au catalogue."
msgstr[1] "%(n)s produits au catalogue."

[.po] 文件是由空行分隔的一系列条目:

  • 第 1–4 行:注释;
  • 第 5–11 行:头部条目:一个空字符串([msgid ""]),其“译文”([msgstr])包含词典信息:语言、字符集以及该语言的复数规则([Plural-Forms]:法语有两种形式,第二种用于任何大于 1 的数字);
  • 第 13–15 行:一个标准条目:[msgid] 是源文本,与模板中所写一致;[msgstr] 是其译文。行 [#:] 指明该文本出现的位置(模板和行号):这是给译者的注释;
  • 第 25–28 行:包含变量的文本。在词典中,变量写作 [%(name)s] (来自 [Python] 的格式字符串语法,示例 10);行 [#, python-format] 向工具标示这一点。译文可以调整变量的位置,或改变其周围的标点(在法语中,感叹号之前有一个空格);
  • 第 47–52 行:复数形式:[msgid] 是单数形式,[msgid_plural] 是 复数形式,译文中的每种形式都有编号([msgstr[0]]、[msgstr[1]]),其顺序由规则 [Plural-Forms] 指定。在法语中,0 和 1 是单数,而在英语中 0 是复数(“0 products”):[gettext] 凭借这条规则知道这一点。这相比案例研究以前版本中使用的“product(s)”是一种改进。

这个文件不是手工编写的。命令:

python manage.py makemessages -l fr

扫描项目的模板和 [Python] 代码,提取所有标记为“待翻译”的文本,并创建或更新 [locale/fr/LC_MESSAGES/django.po] 文件:新文本以空译文添加到其中,已有的译文则保持不变。剩下的只是写出译文,可以使用文本编辑器,也可以使用专门的软件(例如 [Poedit])。命令:

python manage.py compilemessages

随后它将每个 [.po] 文件编译为一个 [.mo] 文件——一种读取速度很快的二进制文件——这正是 [Django] 所使用的文件。编译之后必须重启服务器:词典只会一次性加载。这两个命令使用 [gettext] 的程序([xgettext]、[msgfmt]……),这些程序必须已安装(对于 [Linux],是 [gettext] 软件包;对于 [Windows],例如 mlocati.github.io 网站上发布的二进制文件)。由于示例中已提供 [django.mo] 文件,因此运行该示例无需安装这些软件包。

5.1.3. 语言选择:路由和视图

# config/urls.py:主路由表

from django.urls import path, re_path

from pages import views

urlpatterns = [
    path("", views.home, name="home"),
    path("products", views.products, name="products"),
    # re_path:用正则表达式描述的路由;fr 或 en 以外的
    # 语言不匹配该路由(404)
    re_path(r"^language/(?P<code>fr|en)$", views.change_language, name="language"),
]
  • 第 12 行:[re_path] 使用正则表达式而不是 [path] 的语法(示例 02)来描述路由。[^] 和 [$] 标记路径的开头和结尾;[(?P<code>fr|en)] 是一个命名组:它所识别的文本——[fr] 或 [en] (竖线表示“或”)——通过 [code] 参数传递给视图。其他语言不匹配任何路由:[/language/de] 返回 404 错误。
# pages/views.py:视图对语言一无所知:它们提供
# 数据,由模板翻译并格式化这些数据

from datetime import date

from django.conf import settings
from django.shortcuts import redirect, render
from django.utils.http import url_has_allowed_host_and_scheme
from django.views.decorators.http import require_GET

from .viewmodels import Product


@require_GET
def home(request):
    return render(request, "pages/home.html", {"name": "Marie", "today": date(2026, 9, 23)})


@require_GET
def products(request):
    return render(request, "pages/products.html", {"products": [
        Product("Keyboard", 2500),
        Product("Mouse", 1250),
        Product("Screen", 114900),
    ]})


# GET /language/fr:将选择记在语言 Cookie 中,然后返回
# 上一个页面
@require_GET
def change_language(request, code):
    response = redirect(origin_page(request))
    # 该 Cookie:有效期一年,页面的 JavaScript 无法读取(httponly),
    # 来自其他站点的 POST 请求绝不会携带它(samesite Lax)
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        httponly=True, samesite="Lax")
    return response


# 我们来自的页面(Referer 头部),前提是它属于本站点:若重定向
# 到来自请求的任意地址,就可能把
# 用户送往另一个站点("开放重定向"漏洞)
def origin_page(request):
    referer = request.headers.get("Referer", "")
    # url_has_allowed_host_and_scheme:对相对地址,或主机为
    # 请求主机的绝对地址,返回 true
    if url_has_allowed_host_and_scheme(referer, allowed_hosts={request.get_host()}):
        return referer
    return "/"
  • 第 14–25 行:主页和产品视图不知道语言;它们提供原始数据(名称、日期、以分为单位的金额)。翻译和格式化由模板处理。类 [Product] 具有名称和以分为单位的价格;库 [formats] 就是示例 16 中的那个:其过滤器 [long_date] 以当前语言的“完整”格式写出日期(“Wednesday, September 23, 2026”“mercredi 23 septembre 2026”),其过滤器 [money] 显示 金额;
  • 第 30–37 行:切换语言的视图通过将用户重定向回其来源页面来响应;用户将以新语言回到原来的页面;
  • 第 35–36 行:响应包含一个 Cookie,浏览器会在每个请求中将其发回。[set_cookie] 接收其名称、值和选项:[max_age],即其生存期,以秒为单位(一年);[httponly=True] 使其对页面上的 the [JavaScript] 不可见;[samesite="Lax"] 阻止浏览器在来自其他站点的 POST 请求中发送它。它作为 [Set-Cookie] 头部添加到响应中;
  • 第 43–49 行:原始页面由请求中的 [Referer] 头部指定(其拼写有误,只有一个 [r],这是 HTTP 标准中的写法),浏览器会用包含该链接的页面的 URL 填充它。但这个头部来自客户端,客户端可以在其中放入任何内容。盲目地重定向到这个地址会使我们的应用程序变成开放重定向:带有我们域名的恶意链接可能将用户送到恶意站点。[url_has_allowed_host_and_scheme] 函数位于 [Django] 中([django.utils.http]),用于检查地址是相对地址,还是指向允许的机器之一(此处为请求中的那一台:[request.get_host()]);否则,用户将被重定向到主页。

[Django] 还提供了一个现成的切换语言视图 [django.views.i18n.set_language],它通过表单(POST)完成同样的任务;我们自己编写了一个来演示这一点,并支持通过简单的链接切换语言。

5.1.4. 在模板中翻译

<!doctype html>
{% load static %}
{# LANGUAGE_CODE:请求的语言,"fr" 或 "en" #}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# 标题:页面的 [title] 块,已翻译 #}
  <title>{% block title %}{% endblock %}</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3">
    {% include "fragments/navbar.html" %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • 第 4 行:页面的 [lang] 属性向浏览器、搜索引擎和屏幕阅读器指明其语言;[LANGUAGE_CODE] 是请求的语言,由上下文处理器 [i18n] 提供;
  • 第 9 行:页面标题由页面本身提供,已经翻译(块 [title])。
{# i18n:翻译标签库 #}
{% load i18n %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# translate:按请求的语言翻译一段文本 #}
    <a class="nav-link" href="{% url 'home' %}">{% translate "Home" %}</a>
    <a class="nav-link" href="{% url 'products' %}">{% translate "Products" %}</a>
  </div>
  {# get_available_languages:LANGUAGES 设置中的语言,成对的(代码,名称) #}
  {% get_available_languages as languages %}
  <div class="btn-group btn-group-sm">
    {% for code, name in languages %}
      {# 当前语言高亮显示 #}
      <a class="btn {% if code == LANGUAGE_CODE %}btn-primary{% else %}btn-outline-primary{% endif %}"
         href="{% url 'language' code %}" title="{{ name }}">{{ code|upper }}</a>
    {% endfor %}
  </div>
</nav>
  • 第 2 行:翻译标签位于 [i18n] 库中,每个模板都必须加载它(示例 16);
  • 第 6–7 行:[{% translate %}] 标签返回文本在请求语言中的译文(如果没有译文,则返回文本本身);
  • 第 10–17 行:[{% get_available_languages %}] 标签将 [LANGUAGES] 设置中的语言((代码,名称)对)存储在一个变量中,随后循环对其进行解析([for code, name in languages])。每种语言一个按钮,链接到 [/language/<code>] 视图。当前语言会突出显示([btn-primary],实心按钮)。
{% extends "layout.html" %}
{% load i18n formats %}

{% block title %}{% translate "Welcome" %}{% endblock %}

{% block content %}
  <h1>{% translate "Welcome" %}</h1>
  {# blocktranslate:包含 {{ name }} 变量的文本 #}
  <p>{% blocktranslate %}Hello {{ name }}!{% endblocktranslate %}</p>
  {# with:先格式化日期(long_date 过滤器,见示例 16),再插入文本 #}
  <p>{% blocktranslate with date=today|long_date %}Today is {{ date }}.{% endblocktranslate %}</p>
{% endblock %}
  • 第 4 行:[title] 块,已翻译,供父模板使用;
  • 第 9 行:[{% blocktranslate %}] 标签翻译包含变量的文本:[{{ name }}] 在词典中变为 [%(name)s] 。这里只允许使用简单变量(不能有过滤器或句点);
  • 第 11 行:因此,计算得出的变量只能通过 [with] 包含到文本中:由过滤器 [long_date] 按请求语言格式化的日期,存储在文本中的变量 [date] 里。
{% extends "layout.html" %}
{% load i18n formats %}

{% block title %}{% translate "Our products" %}{% endblock %}

{% block content %}
  <h1>{% translate "Our products" %}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{% translate "Product" %}</th><th class="text-end">{% translate "Price" %}</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          <td>{{ product.name }}</td>
          {# 示例 16 的 money 过滤器:格式取决于语言 #}
          <td class="text-end">{{ product.price_cents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# 复数:count 根据数字 n 选择形式;plural 分隔各个形式 #}
  <p>{% blocktranslate count n=products|length %}{{ n }} product in the catalogue.{% plural %}{{ n }} products in the catalogue.{% endblocktranslate %}</p>
{% endblock %}
  • 第 15 行:过滤器 [money],其结果取决于语言;
  • 第 21 行:复数。[count n=products|length] 返回决定形式的数字([length],示例 14);[{% plural %}] 标签将单数形式与复数形式分隔开,二者都以源语言书写。不过,产品名称不会被翻译:它们是数据,在真实的应用程序中会来自数据库。

在模板之外,翻译由 [django.utils.translation] 模块的函数处理:[gettext("Home")] (通常以简称 [_] 导入:[_("Home")])、用于复数的 [ngettext] ,以及 [gettext_lazy],即仅在使用文本时才执行的“惰性”翻译:对于在加载模块时定义的文本(例如表单字段的标签),当请求的语言尚不可知时,应使用它。案例研究使用了它。

5.1.5. 执行

英语(默认语言)的主页,然后是点击“FR”按钮后的法语主页:

Image

Image

两种语言的产品页面。金额遵循每种语言的惯例:

Image

Image

使用 [curl] 看到的语言切换。选项 [-H] 提供浏览器会发送的头部 [Referer] :

curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: http://localhost:8000/products
Vary: Accept-Language
Content-Language: en
Set-Cookie: django_language=fr; expires=Mon, 27 Sep 2027 17:37:43 GMT; HttpOnly; Max-Age=31536000; Path=/; SameSite=Lax

重定向会将你带回原始页面,并且 Cookie 被设置为持续一年。响应本身仍是英文([Content-Language: en]):语言只是在请求到达时选定的,那时 Cookie 还不存在。指向其他站点的 [Referer] 不会让你被重定向到那里:

curl -i -H "Referer: https://pirate.example/trap" http://localhost:8000/language/fr
1
2
3
4
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /
...

用户回到主页,并留在我们的站点上。最后,是带着 Cookie [django_language=fr] ([-b] 选项,属于 [curl])请求的主页:

curl -b "django_language=fr" http://localhost:8000/
<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Bienvenue</title>
...
    <a class="nav-link" href="/">Accueil</a>
    <a class="nav-link" href="/products">Produits</a>
...
  <h1>Bienvenue</h1>
  <p>Bonjour Marie !</p>
  <p>Nous sommes le mercredi 23 septembre 2026.</p>
...

该 Cookie 没有签名:它以明文传输,用户可以修改它。这不成问题:它不包含任何机密信息,并且 [LocaleMiddleware] 只接受 [LANGUAGES] 设置中指定的语言。下一个示例将说明对 Cookie 可以给予多大程度的信任。没有 Cookie 时,[LocaleMiddleware] 读取浏览器的 [Accept-Language] 头部:[curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/] 会以法语渲染页面。因此这两种机制可以自然地结合:首次访问时使用浏览器的语言,之后使用用户选择的语言。第三种常见做法是将语言放在 URL 中([/fr/products]):此时 [i18n_patterns] 函数(属于 [Django] )会在路由前加上语言前缀,而 [LocaleMiddleware] 从路径中读取它。本案例研究重点关注 Cookie。