Python 项目国际化：使用 Babel 实现多语言支持

如何使用 Babel 实现 Python 项目国际化

• 参考文章：
  • Flask-Babel 使用简介(翻译文档)
  • Python Web 开发中的国际化与本地化处理
  • pythonweb国际化: 国际化flask-babel，gettext，msgfmt，msginit
• 此流程包括两种方式，分别是有配置文件方式和无配置文件方式，可以根据项目需求选择其中一种方式。

---

1. 安装 Babel

无论选择哪种方式，都需要首先安装 Babel：

pip install babel

2. 设置项目目录结构

建议将代码、翻译文件等文件分门别类以便于管理：

my_project/
│
├── src/                     # 源代码目录
│   └── main.py              # 主程序
│
├── locales/                 # 翻译文件目录
│
└── babel.cfg                # Babel 配置文件 (可选)

3. 标记可翻译的文本

在代码中标记需要翻译的文本。例如，在 main.py 中：

from gettext import gettext as _

print(_("Hello, world!"))
print(_("This is a translatable message."))

使用 _() 包裹需要翻译的文本内容。

---

4. 提取可翻译的文本生成文件 —— 生成pot文件

4.1 有配置文件方式（使用 babel.cfg）

4.1.1. 创建 babel.cfg 文件

在项目根目录下创建 babel.cfg 文件，用于指定提取翻译文本的路径和文件类型：

[python: src/**.py]  
encoding = utf-8

在 babel.cfg 文件中，[python: src/**.py] 是一个配置选项，告诉 PyBabel 在提取可翻译文本时，扫描 src/ 目录下的所有 Python 文件（包括子目录中的文件）。这里的 **.py 表示递归地匹配 src/ 目录及其子目录下的所有 Python 文件。

同时，encoding = utf-8 是指定文件编码格式为 UTF-8，确保正确读取和处理文件内容，特别是对于包含非 ASCII 字符的文件。这对于处理多语言翻译非常重要，因为 Python 源代码中的字符串可能会包含不同语言的字符。
该配置文件告诉 Babel 将 src 文件夹下的 .py 文件视为翻译文件来源。

4.1.2. 提取翻译内容

运行以下命令提取可翻译文本，生成 .pot 文件：

pybabel extract -F babel.cfg -o locales/messages.pot .

该命令生成 .pot 文件，用于翻译过程的模板。

这会根据 babel.cfg 文件的配置提取 src 目录中的文本并生成 locales/messages.pot 文件。

• pybabel: Flask-Babel 的命令行工具，用于国际化处理。
• extract: 提取可翻译的字符串。
• -F babel.cfg: 指定配置文件 babel.cfg，定义了哪些文件需要扫描和提取翻译。
• -o locales/messages.pot: 指定输出文件 locales/messages.pot，保存提取的可翻译文本。
• .: 表示从当前目录开始扫描所有文件。

---

4.2 无配置文件方式（直接指定文件路径）

如果不想使用 babel.cfg，可以在命令行中直接指定文件路径来提取翻译内容：

pybabel extract -o locales/messages.pot src/

• pybabel extract: 从源代码中提取可翻译的文本。
• -o locales/messages.pot: 指定输出文件 locales/messages.pot，该文件将包含提取的所有可翻译字符串。
• src/: 指定要扫描的目录，这里是 src/ 目录，PyBabel 会从这个目录中提取 Python 文件中的可翻译文本。

这样可以省略 babel.cfg，Babel 会直接扫描 src/ 目录下的 .py 文件来提取可翻译内容。如果是当前目录请使用“.”

---

5. 后续步骤（通用步骤）

无论使用哪种方式提取文本，后续的步骤都是相同的。

5.1. 初始化翻译文件 —— 生成po文件

生成翻译文件（例如中文 zh_CN），以便翻译文本：

pybabel init -i locales/messages.pot -d locales -l zh_CN

• -i msg.pot: 使用之前提取的 .pot 文件（messages.pot）作为输入。
• -d locales: 指定存放翻译文件的目录（locales）。
• -l zh_CN: 指定目标语言为简体中文 (zh_CN)。

这个命令会根据 messages.pot 文件，在 locales/zh_CN/LC_MESSAGES/ 目录下(执行该命令以后会自动创建)创建一个 .po 文件，供翻译者编辑。

执行后会在 locales/zh_CN/LC_MESSAGES/ 中生成 messages.po 文件。

5.2. 编辑po文件

在 messages.po 中，将 msgstr 设为对应的翻译内容：

msgid "Hello, world!"
msgstr "你好，世界！"

msgid "This is a translatable message."
msgstr "这是一条可翻译的信息。"

5.3. 编译po文件 —— 生成mo文件

编译 .po 文件生成 .mo 文件：

pybabel compile -d locales

编译后的 .mo 文件会生成在 locales/zh_CN/LC_MESSAGES/ 目录下，供程序使用。

5.4. 加载翻译

在代码中加载翻译内容：

import gettext

# 加载翻译
lang = gettext.translation('messages', localedir='locales', languages=['zh_CN'])
lang.install()
_ = lang.gettext  # 使用 _() 调用翻译

# _ = lambda s: s 如果不想翻译，想变成原本的内容，则只需添加该行代码
 
# 输出翻译内容
print(_("Hello, world!"))
print(_("This is a translatable message."))

5.5. 翻译内容更新后的处理的方式

1. 修改源代码
   在源代码中直接修改或添加新的可翻译文本。例如，在 main.py 中：

   print(_("Welcome to the program!"))  # 新增的翻译内容
   print(_("Hello, world!"))
   print(_("This is a translatable message."))  # 已修改的翻译内容
   

2. 更新 .pot 文件
   运行以下命令从代码中提取所有可翻译文本，并更新 .pot 文件（不覆盖现有翻译）：

   pybabel extract -F babel.cfg -o locales/messages.pot .
   

   或者，如果没有 babel.cfg 配置文件，可以直接指定路径：

   pybabel extract -o locales/messages.pot src/
   

3. 合并更新到 .po 文件 —— 类似于git中的merge
   通过以下命令将 .pot 文件中的改动更新到现有的 .po 文件中：

   pybabel update -i locales/messages.pot -d locales
   

   该命令会将新提取的内容合并到所有现有语言的 .po 文件中，而不会覆盖原有的翻译。如果 .po 文件中已有的内容被修改了，则 Babel 会将旧翻译标记为“模糊”翻译（fuzzy），以便译者手动确认。

4. 检查并编辑 .po 文件
   打开 locales/zh_CN/LC_MESSAGES/messages.po 文件，查找新增或更新的内容进行翻译。

   • 新增的翻译会有空的 msgstr，需要填写翻译内容。
   • 更新的翻译（模糊翻译）会带有 #, fuzzy 标签，并包含旧的翻译内容。删除 #, fuzzy 标签并更新 msgstr 以确保翻译准确。

   msgid "Welcome to the program!"
   msgstr "欢迎使用本程序！"
   
   # 原翻译修改为模糊翻译 (fuzzy)
   #, fuzzy
   msgid "This is a translatable message."
   msgstr "这是一条可翻译的信息。"
   

5. 重新编译 .mo 文件
   完成 .po 文件的编辑后，重新编译以生成更新后的 .mo 文件：

   pybabel compile -d locales
   

6. 测试更新的翻译
   运行代码测试新翻译内容，确保在代码中所有修改的翻译内容能够正确加载。

• 注意事项

• 模糊翻译：当 Babel 检测到原文发生了修改，但仍有一部分相似时，会将翻译标记为模糊翻译。模糊翻译不会自动加载，需手动检查并确认。

• 增量更新：更新 .pot 文件和 .po 文件的流程不会影响已经翻译好的内容，仅会添加新的和修改的条目。这样确保了翻译工作的可持续性，不会因为改动覆盖现有的翻译。

• 这样做可以在翻译内容改动后保持翻译文件的同步，确保应用程序的国际化内容准确、及时更新。

---

总结

• 有配置文件方式适合包含多个文件、文件结构复杂的项目。
• 无配置文件方式适合文件结构简单的小项目或测试项目。

Babel 的国际化配置，包含以下步骤：

1. 创建 Babel 配置文件并提取文本。
2. 生成翻译文件，完成翻译。
3. 编译并加载翻译，确保程序可以显示不同语言的内容。

1、新建babel.cfg:
2、提取翻译文本生成翻译模板
pybabel extract -F babel.cfg -o messages.pot .
3、生成翻译文件
pybabel init -i messages.pot -d translations -l zh_Hans-CN
4、在翻译文件中手动输入翻译结果
5、编译翻译文件
pybabel compile -d translations
生成编译文件messages.mo
6、更新翻译
pybabel update -i messages.pot -d translations