5. 国际化
国际化的应用程序以用户的语言显示文本。案例研究提供法语和英语两种语言。原理很简单:视图中不再包含文本,而是包含键 ([MENU.HOME]),并由每种语言的字典 把文本与每个键关联起来。所选语言存储在 Cookie 中。
[Flask] 生态系统为此提供了一个扩展 [Flask-Babel],它依赖标准的翻译系统 [gettext]:文本由工具从代码中提取出来,翻译成 [.po] 文件,然后编译成 [.mo] 文件。这是一个功能强大的系统,但需要专门的工具和一个编译步骤。因此,我们将编写一个读取 JSON 字典的小类:这些文件与案例研究中 [ASP.NET Core MVC]、[NestJS]、和 [Spring MVC] 版本所用的相同,其格式无需任何特殊工具即可读写。另一方面,[Babel] 库仍然用于格式化日期和金额(示例 16)。
5.1. 示例 22:双语应用程序
| 22-i18n/
├── app.py
├── controllers/
│ ├── language.py
│ └── pages.py
├── i18n/
│ ├── en.json
│ └── fr.json
├── static/css/
│ └── styles.css
├── templates/
│ ├── fragments/
│ │ └── navbar.html
│ ├── layout.html
│ └── pages/
│ ├── home.html
│ └── products.html
└── translation/
├── formats.py
└── translator.py
|
5.1.1. 字典
[i18n/fr.json] 文件:
| {
"MENU": {
"HOME": "Accueil",
"PRODUCTS": "Produits"
},
"HOME": {
"TITLE": "Bienvenue",
"HELLO": "Bonjour {name} !",
"DATE": "Nous sommes le {date}."
},
"PRODUCTS": {
"TITLE": "Nos produits",
"NAME": "Produit",
"PRICE": "Prix",
"COUNT": "{n} produit(s) au catalogue."
}
}
|
键在嵌套的 JSON 对象中按主题分组:菜单文本“Home”的完整键为 [MENU.HOME]。文本字符串可以包含占位符,写作 [{name}],它们在翻译时会被替换。文件 [i18n/en.json] 的键与之完全相同:
| {
"MENU": {
"HOME": "Home",
"PRODUCTS": "Products"
},
"HOME": {
"TITLE": "Welcome",
"HELLO": "Hello {name}!",
"DATE": "Today is {date}."
},
"PRODUCTS": {
"TITLE": "Our products",
"NAME": "Product",
"PRICE": "Price",
"COUNT": "{n} product(s) in the catalogue."
}
}
|
5.1.2. 翻译服务:translation/translator.py
| # translation/translator.py:翻译服务
import json
import re
from pathlib import Path
from flask import g
class Translator:
LANGUAGES = ("fr", "en")
DEFAULT_LANGUAGE = "en"
# {name}:文本中的参数
PARAMETER = re.compile(r"\{(\w+)\}")
def __init__(self, folder: Path):
# 语言 -> (完整键 "HOME.HELLO" -> 文本)
self._dictionaries: dict[str, dict[str, str]] = {}
for language in self.LANGUAGES:
with open(folder / f"{language}.json", encoding="utf-8") as file:
self._dictionaries[language] = self._flatten(json.load(file))
# 与 [code] 匹配的受支持语言:"fr" -> "fr";"de" 或 None -> "en"
@classmethod
def language(cls, code: str | None) -> str:
return code if code in cls.LANGUAGES else cls.DEFAULT_LANGUAGE
# translate("HOME.HELLO", name="Marie") -> "Hello Marie!",在
# 当前请求的语言(g.language,见 app.py)
def translate(self, key: str, **parameters) -> str:
# 缺失的键会显示键本身:疏漏在屏幕上一目了然
text = self._dictionaries[g.language].get(key, key)
# 每个 {name} 都被同名参数的值替换
return self.PARAMETER.sub(
lambda m: str(parameters.get(m.group(1), m.group(0))), text)
# { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
@classmethod
def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
result = {}
for key, value in node.items():
full_key = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict):
result.update(cls._flatten(value, full_key))
else:
result[full_key] = value
return result
|
- 第 11–12 行:支持的语言和默认语言——类属性 由该类的所有对象共享,无需对象即可访问([Translator.LANGUAGES]);
- 第 15 行:参数的正则表达式:一个花括号([\{],前面加上 [\] 是因为花括号在正则表达式中有特殊含义)、一个或多个单词字符([\w+]),以及一个右花括号。圆括号捕获参数名称。[re.compile] 一次性解析该表达式;
- 第 17–22 行:构造函数在创建服务时一次性读取字典。[json.load] 把 JSON 文件的内容转换为 [Python] 对象(嵌套字典)。[with open(...) as file] 打开文件,并确保在代码块结束时将其关闭;[encoding="utf-8"] 至关重要,因为默认编码取决于系统(在 [Windows] 下,它并不总是 [UTF-8]);
- 第 25–27 行:类方法 ([@classmethod] 装饰器)接收的是类([cls])而不是对象;它在类上调用:[Translator.language("en")]。它返回与某个代码对应的受支持语言,如果代码未知或缺失,则返回默认语言;
- 第 31–36 行:键的翻译,使用当前请求的语言,该语言读取自 [g.language] (见示例 16)。字典中缺失的键会原样显示:遗漏会立刻在屏幕上显现出来。参数以命名参数的形式接收([**parameters]);正则表达式方法 [sub] 用一个函数的结果替换文本中找到的每个参数——这里是一个匿名函数 ([lambda m: ...]),它接收找到的匹配([m]):[m.group(1)] 是捕获到的名称,[m.group(0)] 是完整文本 [{name}],如果没有提供该参数,就保留它;
- 第 40–48 行:嵌套的 JSON 对象被“展平”为单个字典,其键就是完整的键:[{"MENU": {"HOME": "Home"}}] 变为 [{"MENU.HOME": "Home"}]。该方法是递归的:它对每个嵌套对象调用自身,并把当前键用作前缀。
| # translation/formats.py:以请求的语言格式化的日期和金额(见示例 16)
from datetime import date
from decimal import Decimal
from babel.dates import format_date
from babel.numbers import format_currency
from flask import g
# 以完整文字表示的日期
def long_date(day: date) -> str:
return format_date(day, format="full", locale=g.language)
# 以欧元表示的金额
def money(amount: Decimal) -> str:
return format_currency(amount, "EUR", locale=g.language)
|
示例 16 中的过滤器,这一次使用 [g.language]。[Babel] 既接受单独的语言([fr]、[en]),也接受语言加国家([fr_FR]);对于 [en],它采用美国的惯例。
5.1.4. 配置:app.py
| # app.py:示例 22 的应用
from pathlib import Path
from flask import Blueprint, Flask, g, request
from controllers.language import LANGUAGE_COOKIE, language
from controllers.pages import pages
from translation import formats
from translation.translator import Translator
# Bootstrap,由各示例共享(见示例 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"
def create_app():
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# 翻译服务:各语言字典,在启动时只读取一次
translator = Translator(Path(app.root_path) / "i18n")
app.extensions["translator"] = translator
app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
static_url_path="/bootstrap"))
app.register_blueprint(language)
app.register_blueprint(pages)
# 每个请求的语言:取自 [language] Cookie,否则为英语
@app.before_request
def set_language():
g.language = Translator.language(request.cookies.get(LANGUAGE_COOKIE))
# 在视图中:{{ t('KEY') }}、{{ day | long_date }}、{{ price | money }}
app.add_template_global(translator.translate, "t")
app.add_template_filter(formats.long_date)
app.add_template_filter(formats.money)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 20–21 行:服务,在启动时创建一次。[app.root_path] 是应用程序文件夹(即 [app.py] 所在的文件夹);
- 第 28–30 行:在每个动作之前,请求语言被设置为 [language] Cookie 中的语言(如果它存在且受支持);否则默认为英语。[request.cookies] 是浏览器发送的 Cookie 字典;
- 第 33 行:服务的 [translate] 方法以简短的名称 [t] ([add_template_global] 的第二个参数)作为全局函数提供给视图使用。对象的方法可以像函数一样使用:[translator.translate] 是与对象 [translator] 关联的方法。
5.1.5. 语言选择:controllers/language.py
| # controllers/language.py:语言的选择
from urllib.parse import urlsplit
from flask import Blueprint, abort, redirect, request
from translation.translator import Translator
language = Blueprint("language", __name__)
LANGUAGE_COOKIE = "language"
# GET /language/fr:将选择存入 Cookie,然后返回上一个页面
@language.get("/language/<code>")
def change(code):
if code not in Translator.LANGUAGES:
abort(404)
response = redirect(origin_page())
# 该 Cookie:有效期一年,页面的 JavaScript 无法读取(httponly),
# 来自其他站点的 POST 请求绝不会携带它(samesite)
response.set_cookie(LANGUAGE_COOKIE, code, max_age=365 * 24 * 3600, httponly=True,
samesite="Lax")
return response
# 我们来自的页面(Referer 头部),只保留其路径:
# 若重定向到请求中带来的完整地址,就可能
# 把用户送到另一个站点("开放重定向" 漏洞)
def origin_page() -> str:
url = urlsplit(request.headers.get("Referer", ""))
path = url.path
# "//site.com/..." 会被浏览器理解为
# 另一个站点上的地址:同样予以拒绝
if not path.startswith("/") or path.startswith("//"):
return "/"
return f"{path}?{url.query}" if url.query else path
|
- 第 16 行:未知的语言代码:404;
- 第 18 行:该动作以重定向响应,指向用户来自的页面:用户以新的语言返回到该页面;
- 第 21–22 行:响应中包含一个 Cookie,浏览器会在每次请求时将其发回。[max_age] 是它的生存时间,单位为秒:一年。[httponly=True] 使页面上的 [JavaScript] 无法看到它;[samesite="Lax"] 可防止浏览器在来自其他站点的 POST 请求中发送它。与会话 Cookie(示例 20)不同,这个 Cookie 没有签名:用户修改它也没有问题,因为服务器只接受受支持的语言;
- 第 29–36 行:原始页面由请求中的 [Referer] 头部指定(HTTP 标准中使用的就是这个拼写错误的版本,只有一个 [r]),浏览器会用包含该链接的页面的 URL 来填充它。但这个头部来自客户端,客户端可以在其中放入任何内容。盲目地重定向到这个地址,会使我们的应用程序变成一个*开放重定向*:带有我们域名的恶意链接可能会把用户送到恶意网站。因此,我们只保留 URL 的路径和参数([urlsplit] 将其分解为各个组成部分),并拒绝任何以 [//] 开头的路径,浏览器会把这样的路径解释为另一个站点的地址。
5.1.6. 动作:controllers/pages.py
| # controllers/pages.py:动作对语言一无所知:它们
# 提供数据,由视图负责翻译和格式化
from dataclasses import dataclass
from datetime import date
from decimal import Decimal
from flask import Blueprint, render_template
pages = Blueprint("pages", __name__)
@dataclass
class Product:
name: str
price: Decimal
@pages.get("/")
def home():
return render_template("pages/home.html", name="Marie", today=date(2026, 9, 23))
@pages.get("/products")
def products():
return render_template("pages/products.html", products=[
Product("Keyboard", Decimal("25")),
Product("Mouse", Decimal("12.5")),
Product("Screen", Decimal("1149")),
])
|
动作与语言无关:它们提供原始数据(姓名、日期、金额)。翻译和格式化由视图负责。
5.1.7. 在视图中翻译
| <!doctype html>
{# g.language:请求的语言,"fr" 或 "en" #}
<html lang="{{ g.language }}">
<head>
<meta charset="utf-8">
{# 标题是一个键,由页面提供(title_key 变量),由布局翻译 #}
<title>{{ t(title_key) }}</title>
<link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
<div class="container py-3">
{% include "fragments/navbar.html" %}
<main>
{% block content %}{% endblock %}
</main>
</div>
</body>
</html>
|
- 第 3 行:页面的 [lang] 属性向浏览器、搜索引擎和屏幕阅读器指明页面的语言;
- 第 7 行:页面标题在每个页面中各不相同,但由布局模板负责翻译。每个页面在变量 [title_key] 中提供其标题的键。
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
{# t('KEY'):键的翻译,使用请求的语言 #}
<a class="nav-link" href="/">{{ t("MENU.HOME") }}</a>
<a class="nav-link" href="/products">{{ t("MENU.PRODUCTS") }}</a>
</div>
{# 当前语言高亮显示 #}
<div class="btn-group btn-group-sm">
{% for code in ["fr", "en"] %}
<a class="btn {{ 'btn-primary' if g.language == code else 'btn-outline-primary' }}"
href="/language/{{ code }}">{{ code | upper }}</a>
{% endfor %}
</div>
</nav>
|
- 第 4–5 行:菜单文本,已翻译;
- 第 9–12 行:每种语言一个按钮,指向动作 [/language/<code>]。当前语言被突出显示([btn-primary],实心按钮)。
| {% extends "layout.html" %}
{# 在块之外定义的变量对布局可见 #}
{% set title_key = "HOME.TITLE" %}
{% block content %}
<h1>{{ t("HOME.TITLE") }}</h1>
{# 一个参数:t 函数的关键字参数 #}
<p>{{ t("HOME.HELLO", name=name) }}</p>
{# 先格式化日期,再将其作为 [date] 参数传入 #}
<p>{{ t("HOME.DATE", date=today | long_date) }}</p>
{% endblock %}
|
- 第 3 行:在继承了布局模板的页面中,在块之外定义的变量对布局模板可见:页面就是这样把它的标题键传给布局模板的。(相反,在块内部定义的变量则只在该块内部有效。);
- 第 8 行:文本参数是函数 [t] 的命名参数;
- 第 10 行:日期,按请求的语言格式化,然后作为参数传入。
| {% extends "layout.html" %}
{% set title_key = "PRODUCTS.TITLE" %}
{% block content %}
<h1>{{ t("PRODUCTS.TITLE") }}</h1>
<table class="table table-sm w-auto">
<thead><tr><th>{{ t("PRODUCTS.NAME") }}</th><th class="text-end">{{ t("PRODUCTS.PRICE") }}</th></tr></thead>
<tbody>
{% for product in products %}
<tr>
<td>{{ product.name }}</td>
<td class="text-end">{{ product.price | money }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p>{{ t("PRODUCTS.COUNT", n=products | length) }}</p>
{% endblock %}
|
- 第 17 行:计算得到的参数。不过,产品名称不会被翻译:它们是数据 ,在真实的应用程序中会来自数据库。
5.1.8. 执行
主页,先是英语(默认语言),点击“FR”按钮后变为法语:


产品页面,两种语言各一份。金额遵循各自语言的惯例:


用 [curl] 观察语言切换。选项 [-H] 提供浏览器会发送的头部 [Referer] :
| curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/en
|
| HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 205
Location: /products
Set-Cookie: language=en; Expires=Sun, 26 Sep 2027 13:37:04 GMT; Max-Age=31536000; HttpOnly; Path=/; SameSite=Lax
...
|
重定向把你带回原来的页面,并且 Cookie 被设置为保存一年。指向另一个站点的 [Referer] 不会把你重定向到那里:只保留它的路径。
| curl -i -H "Referer: https://pirate.example/trap" http://localhost:5000/language/en
curl -i -H "Referer: http://localhost:5000//pirate.example/x" http://localhost:5000/language/fr
|
| HTTP/1.1 302 FOUND
...
Location: /trap
HTTP/1.1 302 FOUND
...
Location: /
|
页面 [/trap] 在我们的站点上并不存在:用户会收到 404 错误,但仍停留在我们的站点上。最后,带着 Cookie [language=en] ([curl] 的选项 [-b])请求主页:
| curl -b "language=en" http://localhost:5000/
|
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Welcome</title>
...
<a class="nav-link" href="/">Home</a>
<a class="nav-link" href="/products">Products</a>
...
<h1>Welcome</h1>
<p>Hello Marie!</p>
<p>Today is Wednesday, September 23, 2026.</p>
...
|
选择语言的另一种方式是读取浏览器的 [Accept-Language] 头部(示例 12)。两者经常结合使用:首次访问时使用浏览器的语言,之后使用用户选择的语言。本案例研究侧重于 Cookie,以英语为默认语言。