13.国际化和本地化

在本章我们将讨论如何扩展 Microblog 应用以支持多种语言。作为其中的一部分，你还将学习如何为 flask 命令创建自己的 CLI 扩展。

本章的主题是国际化和本地化，通常缩写为 I18n 和 L10n。为了使我的应用对不会英语的人更加友好，我将在语言翻译机制的帮助下，实施翻译工作流程，来使用多种语言向用户提供服务。

---

Flask-Babel 简介

Flask-Babel 是用于 Flask 应用国际化支持的库。使用 pip 命令安装它：

(venv) $ pip install flask-babel

和其它第三方库一样，先要在 app/__init__.py 中把 Flask-Babel 初始化：

# app/__init__.py

from flask_babel import Babel

def create_app(config):
    app = Flask(__name__)
    babel.init_app(app)
    # ...
    return app

在本章，我的应用会支持英语和汉语两种语言。为了跟踪支持的语言列表，我将在 config.py 添加一个配置变量：

# config.py

class Config(object):
    # ...
    LANGUAGES = ['en', 'zh']

Babel 实例提供了一个 localeselector 装饰器。为每个请求调用装饰器函数以选择用于该请求的语言。我们在 app/__init__.py 中使用它。

# app/__init__.py

from flask import request, current_app
from flask_babel import Babel

@babel.localeselector
def get_locale():
    return request.accept_languages.best_match(current_app.config['LANGUAGES'])

这里我使用了 Flask 中 request 对象的属性 accept_languages。 request 对象提供了一个高级接口，用于处理浏览器端发送的带 Accept-Language 头部的请求。该头部指定了客户端语言和区域设置首选项。该头部的内容可以在浏览器的首选项页面中配置，默认情况下通常从计算机操作系统的语言设置中导入。

我们先在浏览器的开发者工具看看 accept_languages 属性：

Flask 会读取这一属性参数，并记录到 request 对象的 accept_languages 字段中。

request.accept_languages.best_match 方法会根据请求头的 Accept-Language 权重和配置中的语言列表，选择出当前最合适的语言。在本例中，最合适的语言为汉语 zh。

---

标记 Python 源码中的需翻译文本

接下来的任务是在源代码中标记所有需要翻译的文本。文本标记后，Flask-Babel 将扫描所有文件，并使用 gettext 工具将这些文本提取到单独的翻译文件中。不幸的是，这是一个繁琐的任务。

我只会在这里向你展示几个标记操作的示例，更多的代码请去 GitHub 浏览。

标记需翻译文本的方式是将它们封装在一个函数中，该函数调用为 _()，没错，它仅仅是一个下划线。最简单的情况是标记源代码中出现的字符串。下面是一个 flask() 语句的例子：

from flask_babel import _
# ...
flash(_('Your post is now live!'))

_() 函数用于原始语言文本（在这种情况下是英文）的封装。 该函数将使用由 localeselector 装饰器装饰的选择函数，来为给定客户端查找正确的翻译语言。_() 函数随后返回翻译后的文本，在本处，翻译后的文本将成为 flash() 的参数。

但是不可能每个情况都这么简单，来看一个需要拼接字符串的 flash() 调用：

flash('User {} not found!'.format(username))

该文本具有一个安插在静态文本中间的动态组件。_() 函数的语法支持这种类型的文本，但它基于旧版本的字符串替换语法：

flash(_('User %(username)s not found!', username=username))

还有更难处理的情况。 有些字符串文字并非是在发生请求时分配的，比如在应用启动时（例如表单类里面的标签和提示语）。因此在处理这些文本时，无法知道要使用哪种语言。处理这些文本的唯一解决方案是找到一种方法来延迟对字符串的评估，直到它被使用，比如有实际上的请求发生了。

Flask-Babel 提供了一个 lazy_gettext() 函数来处理这种情况：

from flask_babel import lazy_gettext as _l

class LoginForm(FlaskForm):
    username = StringField(_l('Username'), validators=[DataRequired()])
    # ...

在这里，我导入的这个翻译函数被重命名为 _l()，以使其看起来与原始的 _() 相似。这个对象会在稍后的字符串使用时触发翻译。

Flask-Login 插件的闪现消息也是属于浏览器请求之前就生成的内容，所以也需要 lazy_gettext 方法来标记翻译。

from flask_babel import lazy_gettext as _l

login = LoginManager()
login.login_view = "auth.login"
login.login_message = _l("Please log in to access this page.")

---

标记 HTML 模板中的需翻译文本

在前面的章节中，我们知道如何在 Python 源代码中标记需翻译的文本，但这只是该过程的一部分，因为 HTML 模板文件也包含文本。_() 函数也可以在模板中使用。 例如，参考来自 404.html 的这段 HTML 代码：

<h1>File Not Found</h1>

标记翻译之后的版本是：

<h1>{{ _('File Not Found') }}</h1>

请注意，除了用 _() 包装文本外，还需要添加 {{...}} 来强制 _() 函数的执行，否则其会视为模板中的文本字面量。

对于具有动态组件的更复杂的情况，也可以使用参数：

<h1>{{ _('Hi, %(username)s!', username=current_user.username) }}</h1>

_post.html 中有一个更为复杂的例子：

{% set user_link %}
<a href="{{ url_for('auth.user', username=post.author.username) }}">
    {{ post.author.username }}
</a>
{% endset %}
{{ 
  _('%(username)s said: %(when)s',
  username=user_link, 
  when=moment(post.timestamp).fromNow()) 
}}

这里的问题是我希望 username 是一个超链接，指向用户的个人主页，而不仅仅是名字，所以我必须使用 set 和 endset 模板指令创建一个名为 user_link 的中间变量 ，然后将其作为参数传递给翻译函数。

---

提取文本进行翻译

一旦应用所有 _() 和 _l() 都到位了，你可以使用 pybabel 命令将它们提取到一个 .pot 文件中，该文件代表可移植对象模板。这是一个文本文件，其中包含所有标记为需要翻译的文本。这个文件的目的是作为一个模板来为每种语言创建翻译文件。

提取过程需要一个小型配置文件，告诉 pybabel 哪些文件应该被扫描以获得可翻译的文本。下面我们在应用的根目录创建的 babel.cfg 配置文件：

# babel.cfg

[python: app/**.py]
[jinja2: app/templates/**.html]
extensions=jinja2.ext.autoescape,jinja2.ext.with_

前两行分别定义了 Python 和 Jinja2 模板文件的文件名匹配模式。第三行定义了 Jinja2 模板引擎提供的两个扩展，以帮助 Flask-Babel 正确解析模板文件。

使用以下命令来将所有文本提取到 .pot 文件：

(venv) $ pybabel extract -F babel.cfg -k _l -o messages.pot .

pybabel extract 命令读取 -F 选项中给出的配置文件，然后从命令给出的目录（当前目录或本处的 .）扫描与配置的源匹配的目录中的所有代码和模板文件。

默认情况下，pybabel 将查找 _() 以作为文本标记，但我也使用了重命名为 _l() 的延迟版本函数，所以我需要用 -k _l 来告诉该工具也要查找 _l() 函数标记的部分 。-o 选项提供输出文件的名称。

关于该命令的详情请参阅：官方文档。

执行完该命令后会在根目录生成一个 messages.pot 文件。应该注意，messages.pot 文件不需要合并到项目中。这是一个只要再次运行上面的命令，就可以在需要时轻松地重新生成的文件。因此，不需要将该文件提交到源代码管理。

messages.pot 文件的一部分：

# Translations template for PROJECT.
# Copyright (C) 2021 ORGANIZATION
# This file is distributed under the same license as the PROJECT project.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PROJECT VERSION\n"
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
"POT-Creation-Date: 2021-08-03 22:49+0800\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.9.1\n"

#: app/__init__.py:26
msgid "Please log in to access this page."
msgstr ""

#: app/auth/forms.py:21 app/auth/forms.py:27 app/auth/forms.py:45
msgid "Username"
msgstr ""

#: app/auth/forms.py:22 app/auth/forms.py:29 app/auth/forms.py:64
msgid "Password"
msgstr ""

#: app/auth/forms.py:23
msgid "Remember Me"
msgstr "

---

生成语言目录

该过程的下一步是在除了原始语言（在本例中为英语）之外，为每种语言创建一份翻译。 我要从添加汉语（语言代码 zh）开始，所以这样做的命令是：

venv) $ pybabel init -i messages.pot -d app/translations -l zh
creating catalog app/translations\zh\LC_MESSAGES\messages.po based on messages.pot

pybabel init 命令将 messages.pot 文件作为输入，-d 选项指定该语言的翻译文本的输出目录，-l 选项指定的是翻译语言。本例中将输出在 app/translations 目录。 该命令将在该目录内为汉语数据文件创建一个 zh 子目录。 内含的 \zh\LC_MESSAGES\messages.po 文件就是我们需要进行翻译文本的文件。

app\translations\zh\LC_MESSAGES\messages.po 文件的局部：

# app\translations\zh\LC_MESSAGES\messages.po

# Chinese translations for PROJECT.
# Copyright (C) 2021 ORGANIZATION
# This file is distributed under the same license as the PROJECT project.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2021.
#
msgid ""
msgstr ""
"Project-Id-Version: PROJECT VERSION\n"
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
"POT-Creation-Date: 2021-08-03 22:49+0800\n"
"PO-Revision-Date: 2021-08-03 22:49+0800\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: zh\n"
"Language-Team: zh <LL@li.org>\n"
"Plural-Forms: nplurals=1; plural=0\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.9.1\n"

#: app/__init__.py:26
msgid "Please log in to access this page."
msgstr ""

#: app/auth/routes.py:123 app/auth/routes.py:138
#, python-format
msgid "User %(username)s not found."
msgstr ""

#: app/templates/_post.html:13
#, python-format
msgid "%(username)s said: %(when)s"
msgstr ""

需要被翻译为汉语的语句都会被提取到这里，我们的翻译工作就在本文件里操作。如果你想支持其他语言，只需要替换上各自的语言代码重复上述命令，就能使得每种语言都有一个包含 messages.po 文件的存储库。

对每个文本，都会展示其在应用中的引用位置。 然后，msgid 行包含原始语言的文本，后面的 msgstr 行包含一个空字符串。 这些空字符串需要被编辑，以使目标语言中的文本内容被填充。

翻译完成后的 app\translations\zh\LC_MESSAGES\messages.po 文件局部：

#: app/__init__.py:26
msgid "Please log in to access this page."
msgstr "请登录以继续浏览本页面。"

#: app/auth/routes.py:123 app/auth/routes.py:138
#, python-format
msgid "User %(username)s not found."
msgstr "用户 %(username)s 不存在。"

#: app/templates/_post.html:13
#, python-format
msgid "%(username)s said: %(when)s"
msgstr "%(username)s %(when)s 说："

messages.po 文件是一种用于翻译的源文件，这个文件需要被编译后才可以被应用程序使用。要编译应用程序的所有翻译，可以使用 pybabel compile 命令，如下所示：

(venv) $ pybabel compile -d app/translations
compiling catalog app/translations\zh\LC_MESSAGES\messages.po to 
app/translations\zh\LC_MESSAGES\messages.mo

此操作在每个语言存储库中的 messages.po 旁边生成了一个 messages.mo 文件。.mo 文件是 Flask-Babel 用于为应用程序加载翻译的二进制文件。

完成这一步后，我们再来刷新我们的应用，可以看到翻译已经起作用（前提是你的计算机系统和浏览器语言设定为汉语）。

如果你想继续使用英文版，可以把计算机系统的语言换为英语。

另一种方法是修改 localeselector 函数，让它始终返回一种语言来强制实现。 对英语，你可以这样做：

# app/__init__.py

@babel.localeselector
def get_locale():
    # return request.accept_languages.best_match(app.config['LANGUAGES'])
    return 'en'

---

更新翻译

处理翻译时的一个常见情况是，即使未全部完成翻译，也可能要使用翻译文件。一个不完整的 messages.po 文件也是可以被编译的，已翻译的部分将被使用，而未翻译的部分将使用原始语言。随后，你可以继续处理翻译并再次编译，以便在翻译取得进展时更新 messages.mo 文件。

如果在使用 _() 标记需翻译文本时错过了一些文本，则会出现另一种常见情况。在这种情况下，你会发现你错过的那些文本依然保持为英文，因为 Flask-Babel 未能识别它们。 如果发生这种情况时，我们新添加 _() 或 _l() 标记，然后执行更新过程，这包括两个步骤：

(venv) $ pybabel extract -F babel.cfg -k _l -o messages.pot .
(venv) $ pybabel update -i messages.pot -d app/translations

extract 命令与我之前执行的命令相同，但现在它会生成 messages.pot 的新版本，其中包含所有以前的文本以及新添加的用 _() 或 _l() 标记的文本。

update 调用采用新的 messages.pot 文件并将其合并到与项目相关的所有 messages.po 文件中。 这将是一个智能合并，其中任何现有的文本将被单独保留，而只有在 messages.pot 中添加或删除的条目才会受到影响。

messages.po 文件更新后，你就可以继续新的测试了，再次编译它，以便对应用生效。

---

翻译日期和时间

现在，我已经为 Python 代码和 HTML 模板中的所有文本提供了完整的汉语翻译，但是现在还有一些内容以英文显示。就是由 Flask-Moment 和 moment.js 生成的时间戳，显然这些时间戳并未包含在翻译工作中，因为这些包生成的文本都不是应用程序源代码或模板的一部分。

moment.js 库原生支持本地化和国际化，所以我需要做的就是配置适当的语言。Flask-Babel 通过 get_locale() 函数返回给定请求的语言和语言环境，所以我要做的就是将语言环境添加到 Flask 的全局对象 g 对象中，以便我可以从基础模板中访问它。

# app\main\routes.py

from flask import g
from flask_babel import get_locale

# ...

@main_routes.before_app_request
def before_app_request():
    if str(get_locale()) == 'zh':
        local = 'zh-CN'
    else:
        local = 'en'
    g.locale = local

这里我把这个操用 before_app_request 装饰器修饰，而非像以前那样使用 before_request 装饰器，是因为使用 before_request 后只对该函数所注册的蓝图下的视图函数有效，比如 @main_routes.before_request 就只对注册在 main_routes 蓝图之下的视图函数有效，当我浏览 auth_routes 下注册的页面时，这部分代码就不会被调用。

使用了 `before_app_request装饰器后，每一次请求发生的时候，不管该视图函数注册于哪一个蓝图，都会触发上面代码，通过get_locale()方法获取当前浏览器的语言，并把它写入到全局变量g`` 之中。

注意：Flask-Bable 中使用的汉语代号为 zh，而在 moment.js 中他还会进一步细分为 zh-cCN、zh-hk 、zh-tw 等，所以我们这里用一个 if 语句来做一个转换。

现在我有了 g.locale，可以从基础模板中访问它，并以正确的语言配置 moment.js：

...
# app/templates/base.html

{% block scripts %}
  {{ super() }}
  {{ moment.include_moment() }}
  {{ moment.lang(g.locale) }}
{% endblock %}

现在所有的日期和时间都与文本使用相同的语言了。 你可以在下面看到汉语的外观：

---

命令行增强

现在应用的国际化和本地化已经基本完成，但是你可能会决定 pybabel 系列命令有点长，难以记忆。我将利用这个机会向你展示如何创建与 flask 命令集成的自定义命令。

到目前为止，我们已经使用过 Flask-Migrate 扩展提供的 flask run、flask shell 和几个 flask db 子命令。将我们自定义的新命令添加到 flask 应用上其实也很容易。我现在要做的就是创建一些简单的命令，并用这个应用特有的参数触发 pybabel 命令。

我预想中要添加的命令是：

• flask translate init LANG 用于添加新语言（LANG 为代表语言代号的参数）
• flask translate update 用于更新所有语言存储库
• flask translate compile 用于编译所有语言存储库

我们把这些命令放在一个名为 app/cli.py 的新模块中：

# app/cli.py

import click
import os
from flask.cli import AppGroup

translate = AppGroup('translate')


@translate.command('init')
@click.argument('lang')
def init(lang):
    """Initialize a new language."""
    if os.system('pybabel extract -F babel.cfg -k _l -o messages.pot .'):
        raise RuntimeError('extract command failed')
    if os.system(
            'pybabel init -i messages.pot -d app/translations -l ' + lang):
        raise RuntimeError('init command failed')
    os.remove('messages.pot')

@translate.command('update')
def update():
    """Update all languages."""
    if os.system('pybabel extract -F babel.cfg -k _l -o messages.pot .'):
        raise RuntimeError('extract command failed')
    if os.system('pybabel update -i messages.pot -d app/translations'):
        raise RuntimeError('update command failed')
    os.remove('messages.pot')

@translate.command('compile')
def compile():
    """Compile all languages."""
    if os.system('pybabel compile -d app/translations'):
        raise RuntimeError('compile command failed')

在这里我们先用 translate = AppGroup('translate') 定义一个名为 translate 的命令组，下面三个命令 init、update、compile 注册在该命令组上。这样我们使用 $ flask translate 开头的命令来调用这三个命令。

因为 init 命令是需要带上参数的，我们使用 Python 的 click 模块来实现。

现在我们这样调用这三个命令：

(venv) $ flask translate init zh

(venv) $ flask translate compile

(venv) $ flask translate update

---

本文源码：https://github.com/SingleDiego/Flask-Tutorial-Source-Code/tree/SingleDiego-patch-13