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”按钮后的法语主页:


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


使用 [curl] 看到的语言切换。选项 [-H] 提供浏览器会发送的头部 [Referer] :
| curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/fr
|
| 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
|
| 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。