flask|Flask Mega-Tutorial V2.0 第13章（I18n和L10n） python|flask|mega-Tutorial|i18n|l10n

最近在Flask Web Development作者博客看到第二版Flask Mega-Tutorial已在2017年底更新，现翻译给大家参考，希望帮助大家学习flask。

这是Flask Mega-Tutorial系列的第十三章，其中我将告诉您如何扩展Microblog以支持多种语言。作为这项工作的一部分，您还将学习如何为flask命令创建自己的CLI扩展。
供您参考，以下是本系列文章的列表。

第1章：Hello, World！
第2章：模板
第3章：Web表单
第4章：数据库
第5章：用户登录
第6章：配置文件页面和头像
第7章：错误处理
第8章：关注与被关注
第9章：分页
第10章：电子邮件支持
第11章：整容
第12章：日期和时间
第13章：I18n和L10n（本文）
第14章：Ajax
第15章：大型应用程序结构
第16章：全文搜索
第17章：在Linux上部署
第18章：在Heroku上部署
第19章：Docker容器上的部署
第20章：一些JavaScript Magic
第21章：用户通知
第22章：后台工作
第23章：应用程序编程接口（API）

注意1：如果您正在寻找本教程的旧版本，请在此处。
注意2：如果您想在此博客上支持我的工作，或者只是没有耐心等待每周的文章，我将提供完整的本教程版本，打包成电子书或视频集。欲了解更多信息，请访问courses.miguelgrinberg.com。
本章的主题是国际化和本地化，通常缩写为I18n和L10n。为了使我的应用程序对不说英语的人友好，我将实现一个翻译工作流程，该工作流程将在语言翻译人员的帮助下，允许我以多种语言向用户提供该应用。
本章的GitHub链接是：Browse，Zip，Diff。
Flask-Babel简介您可能会猜到，有一个Flask插件，可以使翻译工作变得非常容易。该扩展名为Flask-Babel，可以使用pip安装：

(venv) $ pip install flask-babel

Flask-Babel的初始化与大多数其他Flask插件一样：
app / __ init__.py：Flask-Babel实例。

# ... from flask_babel import Babelapp = 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。该对象提供了一个高级接口，用于处理客户端发送的带Accept-Language头部请求。该头部指定了客户端语言和区域设置首选项。该头部的内容可以在浏览器的首选项页面中配置，默认情况下通常从计算机操作系统的语言设置中导入。大多数人甚至不知道存在这样的设置，但是这是有用的，因为应用可以根据每个语言的权重，提供优选语言的列表。为了满足你的好奇心，下面是一个复杂的Accept-Languages头部的例子：

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

这表示丹麦语（da）是首选语言（默认权重= 1.0），其后是权重为0.8的英式英语（en-GB），最后是权重为0.7的通用英语（en）。
要选择最佳语言，您需要将客户端请求的语言列表与应用程序支持的语言进行比较，并使用客户端提供的权重找到最佳语言。这样做的逻辑有些复杂，但是都封装在best_match()方法中，该方法将应用提供的语言列表作为参数，并返回最佳选择。
标记文本以在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 _lclass 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代码段：

File Not Found

支持翻译的版本变为：

{{ _('File Not Found') }}

请注意，这里除了用来包装文本_()外，还需要添加一些内容{{ ... }}，以强制_()对进行翻译，而不是将其视为模板中的文字/文本。
对于具有动态组件的更复杂的短语，也可以使用参数：

{{ _('Hi, %(username)s!', username=current_user.username) }}

_post.html中有一个特别棘手的情况，我花了一些时间才弄清楚：

{% set user_link %}{{ post.author.username }}{% endset %} {{ _('%(username)s said %(when)s', username=user_link, when=moment(post.timestamp).fromNow()) }}

这里的问题是，我希望username是一个指向用户个人资料页面的超链接，而不仅仅是名称，因此我不得不使用set和endset模板指令创建一个称为user_link的中间变量，然后将其作为参数传递给翻译功能。
正如我上面提到的，您可以下载应用的一个版本，其中的Python源代码和模板中都已被标记成可翻译文本。
提取文字进行翻译一旦应用所有_()和_l()都到位了，你可以使用pybabel命令将它们提取到一个*.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。以下是西班牙语messages.po开头的若干行：

# Spanish translations for PROJECT. # Copyright (C) 2017 ORGANIZATION # This file is distributed under the same license as the PROJECT project. # FIRST AUTHOR , 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 \n" "Language: es\n" "Language-Team: es \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，可用于所有主要操作系统。如果您熟悉vim，则po.vim插件提供了一些键映射，这些键映射，使处理这些文件更加容易。
添加翻译后，您可以在下面看到西班牙语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"

本章的下载包还包含此文件以及所有翻译，所以你不必担心这部分的翻译工作。
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，这是“设置”页面的“高级”部分：

flask|Flask Mega-Tutorial V2.0 第13章（I18n和L10n）

文章图片

如果你不想更改浏览器设置，另一种方法是通过使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

【flask|Flask Mega-Tutorial V2.0 第13章（I18n和L10n）】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 %}

现在，所有日期和时间都应该以与文本相同的语言显示。在下面，您可以看到该应用程序的西班牙语外观：

文章图片

此时，除用户在用户动态或个人资料说明中提供的文本外，所有其他的文本均可翻译成其他语言。
命令行增强您可能会同意我的观点，pybabel命令有点长且难以记住。我将利用这个机会向您展示如何创建与flask命令集成的自定义命令。到目前为止，您已经看到我使用Flask-Migrate扩展提供的flask run，flask shell和flask db几个子命令。将应用特定的命令添加到flask实际上也很容易。所以我现在要做的就是创建一些简单的命令，并用这个应用特有的参数触发pybabel命令。我要添加的命令是：

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

babel extract步骤不会设置为一个命令，因为生成messages.pot文件始终是运行init或update命令的先决条件，因此这些命令的执行将会生成翻译模板文件作为临时文件。
Flask的所有命令行操作都依赖于Click。像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修饰符定义语言代码。单击将命令中提供的值作为参数传递给处理程序函数，然后将参数合并到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: --helpShow this message and exit.Commands: compileCompile all languages. initInitialize a new language. updateUpdate all languages.

因此，现在，工作流程变得更加简单，无需记住冗长而复杂的命令。要添加新语言，请使用：