> For the complete documentation index, see [llms.txt](https://luhuisicnu.gitbook.io/the-flask-mega-tutorial-zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://luhuisicnu.gitbook.io/the-flask-mega-tutorial-zh/di-shi-san-zhang-guo-ji-hua-he-ben-di-hua.md).

# 第十三章：国际化和本地化

本文翻译自[The Flask Mega-Tutorial Part XIII: I18n and L10n](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-xiii-i18n-and-l10n)

这是Flask Mega-Tutorial系列的第十三部分，我将告诉你如何扩展Microblog应用以支持多种语言。 作为其中的一部分，你还将学习如何为flask命令创建自己的CLI扩展。

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

*本章的GitHub链接为：*[*Browse*](https://github.com/miguelgrinberg/microblog/tree/v0.13)*,* [*Zip*](https://github.com/miguelgrinberg/microblog/archive/v0.13.zip)*,* [*Diff*](https://github.com/miguelgrinberg/microblog/compare/v0.12...v0.13)*.*

## Flask-Babel简介

你猜对了，[Flask-Babel](https://pythonhosted.org/Flask-Babel/)正是用于简化翻译工作的。可以使用pip命令安装它：

```
(venv) $ pip install flask-babel
```

Flask-Babel的初始化与之前的插件类似：

`app/__init__.py`: Flask-Babel实例。

```
# ...
from flask_babel import Babel

app = Flask(__name__)
# ...
babel = Babel(app)
```

作为本章的一部分，我将向你展示如何将应用翻译成西班牙语，因为我碰巧会这种语言。 我当然也可以与翻译机制合作来支持其他语言。 为了跟踪支持的语言列表，我将添加一个配置变量：

*config.py*：支持的语言列表。

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

我为本应用使用双字母代码来表示语言种类，但如果你需要更具体，还可以添加国家代码。 例如，你可以使用`en-US`，`en-GB`和`en-CA`来支持美国、英国和加拿大的英语以示区分。

`Babel`实例提供了一个`localeselector`装饰器。 为每个请求调用装饰器函数以选择用于该请求的语言：

`app/__init__.py`：选择最匹配的语言。

```
from flask import request

# ...

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

这里我使用了Flask中`request`对象的属性`accept_languages`。 `request`对象提供了一个高级接口，用于处理客户端发送的带[Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)头部的请求。 该头部指定了客户端语言和区域设置首选项。 该头部的内容可以在浏览器的首选项页面中配置，默认情况下通常从计算机操作系统的语言设置中导入。 大多数人甚至不知道存在这样的设置，但是这是有用的，因为应用可以根据每个语言的权重，提供优选语言的列表。 为了满足你的好奇心，下面是一个复杂的`Accept-Languages`头部的例子：

```
Accept-Language: da, en-gb;q=0.8, en;q=0.7
```

这表示丹麦语（`da`）是首选语言（默认权重= 1.0），其次是英式英语（`en-GB`），其权重为0.8，最后是通用英语（`en`），权重为0.7。

要选择最佳语言，你需要将客户请求的语言列表与应用支持的语言进行比较，并使用客户端提供的权重，查找最佳语言。 这样做的逻辑有点复杂，但它已经全部封装在`best_match()`方法中了，该方法将应用提供的语言列表作为参数并返回最佳选择。

## 标记文本以在Python源代码中执行翻译

好吧，坏消息来了。 支持多语言的常规流程是在源代码中标记所有需要翻译的文本。 文本标记后，Flask-Babel将扫描所有文件，并使用[gettext](https://www.gnu.org/software/gettext/)工具将这些文本提取到单独的翻译文件中。 不幸的是，这是一个繁琐的任务，并且是启用翻译的必要条件。

我将在这里向你展示标记操作的几个示例，你也可以从[下载包](https://github.com/miguelgrinberg/microblog/tree/v0.13)获取本章完整的更改集，当然，也可以直接查看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插件只要将用户重定向到登录页面，就会闪现消息。 此消息为英文，来自插件本身。 为了确保这个消息也能被翻译，我将重写默认消息，并用`_l()`函数进行延迟处理：

```
login = LoginManager(app)
login.login_view = 'login'
login.login_message = _l('Please log in to access this page.')
```

## 标记文本以在模板中进行翻译

在前面的章节中，你已经看到了如何在Python源代码中标记可翻译的文本，但这只是该过程的一部分，因为模板文件也包含文本。 `_()`函数也可以在模板中使用，所以过程非常相似。 例如，参考来自*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('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`的中间变量 ，然后将其作为参数传递给翻译函数。

正如我上面提到的，你可以[下载](https://github.com/miguelgrinberg/microblog/tree/v0.13)该版本的应用，其中的Python源代码和模板中都已被标记成可翻译文本。

## 提取文本进行翻译

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

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

*babel.cfg*：PyBabel配置文件。

```
[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`来告诉该工具也要查找它 。 `-o`选项提供输出文件的名称。

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

## 生成语言目录

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

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

`pybabel init`命令将*messages.pot*文件作为输入，并将语言目录写入`-d`选项中指定的目录中，`-l`选项中指定的是翻译语言。 我将在*app/translations*目录中安装所有翻译，因为这是Flask-Babel默认提取翻译文件的地方。 该命令将在该目录内为西班牙数据文件创建一个*es*子目录。 特别是，将会有一个名为*app/translations/es/LC\_MESSAGES/messages.po*的新文件，是需要翻译的文件路径。

如果你想支持其他语言，只需要各自的语言代码重复上述命令，就能使得每种语言都有一个包含*messages.po*文件的存储库。

在每个语言存储库中创建的`messages.po`文件使用的格式是语言翻译的事实标准，使用的格式为[gettext](http://www.gnu.org/software/gettext/)。 以下是西班牙语*messages.po*开头的若干行：

```
# Spanish translations for PROJECT.
# Copyright (C) 2017 ORGANIZATION
# This file is distributed under the same license as the PROJECT project.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2017.
#
msgid ""
msgstr ""
"Project-Id-Version: PROJECT VERSION\n"
"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
"POT-Creation-Date: 2017-09-29 23:23-0700\n"
"PO-Revision-Date: 2017-09-29 23:25-0700\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: es\n"
"Language-Team: es <LL@li.org>\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.5.1\n"

#: app/email.py:21
msgid "[Microblog] Reset Your Password"
msgstr ""

#: app/forms.py:12 app/forms.py:19 app/forms.py:50
msgid "Username"
msgstr ""

#: app/forms.py:13 app/forms.py:21 app/forms.py:43
msgid "Password"
msgstr ""
```

如果你跳过首段，可以看到后面的是从`_()`和`_l()`调用中提取的字符串列表。 对每个文本，都会展示其在应用中的引用位置。 然后，`msgid`行包含原始语言的文本，后面的`msgstr`行包含一个空字符串。 这些空字符串需要被编辑，以使目标语言中的文本内容被填充。

有很多翻译应用程序与`.po`文件一起工作。 如果你擅长编辑文本文件，量少的时候也就罢了，但如果你正在处理大型项目，可能会推荐使用专门的编辑器。 最流行的翻译应用程序是开源的[poedit](http://www.poedit.net/)，可用于所有主流操作系统。 如果你熟悉vim，那么[po.vim](https://vim.sourceforge.io/scripts/script.php?script_id=695) 插件会提供一些键值映射，使得处理这些文件更加轻松。

在添加翻译后，你可以在下面看到一部分西班牙语*messages.po*：

```
#: app/email.py:21
msgid "[Microblog] Reset Your Password"
msgstr "[Microblog] Nueva Contraseña"

#: app/forms.py:12 app/forms.py:19 app/forms.py:50
msgid "Username"
msgstr "Nombre de usuario"

#: app/forms.py:13 app/forms.py:21 app/forms.py:43
msgid "Password"
msgstr "Contraseña"
```

本章的[下载包](https://github.com/miguelgrinberg/microblog/tree/v0.13)中包含所有翻译，此文件当然也在其中，所以你不必担心这部分的翻译工作。

*messages.po*文件是一种用于翻译的源文件。 当你想开始使用这些翻译后的文本时，这个文件需要被编译成一种格式，这种格式在运行时可以被应用程序使用。 要编译应用程序的所有翻译，可以使用`pybabel compile`命令，如下所示：

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

此操作在每个语言存储库中的*messages.po*旁边添加*messages.mo*文件。 *.mo*文件是Flask-Babel将用于为应用程序加载翻译的文件。

在为西班牙语或任何其他添加到项目中的语言创建*messages.mo*文件之后，可以在应用中使用这些语言。 如果你想查看应用程序以西班牙语显示的方式，则可以在Web浏览器中编辑语言配置，以将西班牙语作为首选语言。 对Chrome，这是设置页面的高级部分：

![Chrome语言选项](https://camo.githubusercontent.com/2d76573f0290f3dd83835a44fa550a9a8f61fb46/687474703a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f343936313532382d653934333939316565623035633266632e2e706e673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430)

如果你不想更改浏览器设置，另一种方法是通过使`localeselector`函数始终返回一种语言来强制实现。 对西班牙语，你可以这样做：

`app/__init__.py`：选择最佳语言。

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

使用为西班牙语配置的浏览器运行该应用或返回`es`的`localeselector`函数，将使所有文本在使用该应用时显示为西班牙文。

## 更新翻译

处理翻译时的一个常见情况是，即使翻译文件不完整，你也可能要开始使用翻译文件。 这是非常好的，你可以编译一个不完整的*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代码和模板中的所有文本提供了完整的西班牙语翻译，但是如果你使用西班牙语运行应用并且是一个很好的观察者，那么会注意到还有一些内容以英文显示。 我指的是由Flask-Moment和moment.js生成的时间戳，显然这些时间戳并未包含在翻译工作中，因为这些包生成的文本都不是应用程序源代码或模板的一部分。

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

*app/routes.py*：存储选择的语言到flask.g中。

```
# ...
from flask import g
from flask_babel import get_locale

# ...

@app.before_request
def before_request():
    # ...
    g.locale = str(get_locale())
```

Flask-Babel的`get_locale()`函数返回一个本地语言对象，但我只想获得语言代码，可以通过将该对象转换为字符串来获取语言代码。 现在我有了`g.locale`，可以从基础模板中访问它，并以正确的语言配置moment.js：

*app/templates/base.html*：为moment.js设置本地语言

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

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

![西班牙语的Microblog](https://camo.githubusercontent.com/184276bb21253e48f51cce8515403602fddd8655/687474703a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f343936313532382d333335663865653937333630346438302e2e706e673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430)

此时，除用户在用户动态或个人资料说明中提供的文本外，所有其他的文本均可翻译成其他语言。

## 命令行增强

你可能会同意我的看法，pybabel命令有点长，难以记忆。 我将利用这个机会向你展示如何创建与`flask`命令集成的自定义命令。 到目前为止，你已经看到我使用Flask-Migrate扩展提供的`flask run`、`flask shell`和几个`flask db`子命令。 将应用特定的命令添加到`flask`实际上也很容易。 所以我现在要做的就是创建一些简单的命令，并用这个应用特有的参数触发`pybabel`命令。 我要添加的命令是：

* `flask translate init LANG`用于添加新语言
* `flask translate update`用于更新所有语言存储库
* `flask translate compile`用于编译所有语言存储库

`babel export`步骤不会设置为一个命令，因为生成*messages.pot*文件始终是运行`init`或`update`命令的先决条件，因此这些命令的执行将会生成翻译模板文件作为临时文件。

Flask依赖[Click](http://click.pocoo.org/5/)进行所有命令行操作。 像`translate`这样的命令是几个子命令的根，它们是通过`app.cli.group()`装饰器创建的。 我将把这些命令放在一个名为*app/cli.py*的新模块中：

*app/cli.py*：翻译命令组

```
from app import app

@app.cli.group()
def translate():
    """Translation and localization commands."""
    pass
```

该命令的名称来自被装饰函数的名称，并且帮助消息来自文档字符串。 由于这是一个父命令，它的存在只为子命令提供基础，函数本身不需要执行任何操作。

`update`和`compile`很容易实现，因为它们没有任何参数：

*app/cli.py*：更新子命令和编译子命令：

```
import os

# ...

@translate.command()
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()
def compile():
    """Compile all languages."""
    if os.system('pybabel compile -d app/translations'):
        raise RuntimeError('compile command failed')
```

请注意，这些函数的装饰器是如何从`translate`父函数派生的。 这似乎令人困惑，因为`translate()`是一个函数，但它是Click构建命令组的标准方式。 与`translate()`函数相同，这些函数的文档字符串在`--help`输出中用作帮助消息。

你可以看到，对于所有命令，运行它们并确保返回值为零（这意味着命令没有返回任何错误）。 如果命令错误，那么我会引发一个`RuntimeError`，这会导致脚本停止。 `update()`函数在同一个命令中结合了`extract`和`update`步骤，如果一切都成功的话，它会在更新完成后删除*messages.pot*文件，因为当再次需要这个文件时，可以很容易地重新生成 。

`init`命令将新的语言代码作为参数。 这是其执行流程：

*app/cli.py*：Init子命令。

```
import click

@translate.command()
@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')
```

该命令使用`@click.argument`装饰器来定义语言代码。 Click将命令中提供的值作为参数传递给处理函数，然后将该参数并入到`init`命令中。

启用这些命令的最后一步是导入它们，以便注册命令。 我决定在顶级目录的*microblog.py*文件中执行此操作：

*microblog.py*：注册命令。

```
from app import cli
```

这里我唯一需要做的就是导入新的*cli.py*模块，不需要做任何事情，因为导入操作会导致命令装饰器运行并注册命令。

此时，运行`flask --help`将列出`translate`命令作为选项。 `flask translate --help`将显示我定义的三个子命令：

```
(venv) $ flask translate --help
Usage: flask translate [OPTIONS] COMMAND [ARGS]...

  Translation and localization commands.

Options:
  --help  Show this message and exit.

Commands:
  compile  Compile all languages.
  init     Initialize a new language.
  update   Update all languages.
```

所以现在工作流程就简便多了，而且不需要记住长而复杂的命令。 要添加新的语言，请使用：

```
(venv) $ flask translate init <language-code>
```

在更改`_()`和`_l()`语言标记后更新所有语言：

```
(venv) $ flask translate update
```

在更新翻译文件后编译所有语言：

```
(venv) $ flask translate compile
```