13.2 翻译文件处理

Django 6 翻译文件处理完整教程：从makemessages到po/mo文件与语法应用

Django 6中文教程

这篇Django 6教程详细讲解了翻译文件处理全流程，包括使用makemessages命令提取翻译字符串、编辑po文件和编译mo文件，以及在模板和Python代码中应用翻译语法，适合初学者快速上手国际化开发。

Django 6 翻译文件处理详细教程

欢迎来到Django 6的翻译文件处理教程！如果你是Django新手，别担心——本指南会从基础开始，一步步带你掌握如何在Django项目中处理多语言翻译。我们将覆盖从提取翻译字符串到实际应用的全过程，确保内容详细易懂。

引言：什么是Django翻译？

在Django中，国际化（Internationalization，简称i18n）和本地化（Localization，简称l10n）是支持多语言应用的核心功能。翻译文件处理让你可以为不同语言的用户提供本地化内容，提升用户体验。Django通过.po和.mo文件来管理翻译，并提供了简单命令和语法来集成翻译到项目中。

前提条件

在开始之前，请确保：

已安装Python 3.8或更高版本。
已安装Django 6（可通过 pip install django 安装）。
有一个简单的Django项目设置，例如使用 django-admin startproject myproject 创建。

第1步：提取翻译字符串（使用makemessages命令）

提取翻译字符串是翻译的第一步，Django提供了 makemessages 命令来自动扫描你的代码和模板，找出需要翻译的字符串。

如何运行makemessages命令

在项目根目录下（即包含 manage.py 的目录），打开终端或命令行。
运行以下命令来为特定语言（例如简体中文）提取字符串：
```
django-admin makemessages -l zh_Hans
```
- -l zh_Hans 指定语言代码（zh_Hans代表简体中文）。你可以根据需要替换为其他语言，如 en 代表英语。
如果这是第一次运行，Django会创建一个 locale 文件夹，其中包含一个子文件夹（如 zh_Hans/LC_MESSAGES/），并生成一个 .po 文件（如 django.po）。

makemessages命令详解

作用：扫描项目中的所有.py文件、.html模板文件以及其他支持的文件，提取标记为可翻译的字符串。
关键参数：
- -l：指定语言代码，例如 -l zh_Hans。
- --all：提取所有语言的翻译字符串（但通常推荐逐个语言处理）。
- --ignore：忽略特定目录或文件。
注意事项：确保在项目的 settings.py 中已启用国际化设置，例如 USE_I18N = True。

提取完成后，你会在 locale/zh_Hans/LC_MESSAGES/ 目录下找到 django.po 文件，这就是下一步要编辑的翻译文件。

第2步：编辑翻译文件（po文件）

.po 文件（Portable Object文件）是文本格式的翻译文件，包含原始字符串和对应的翻译。你需要手动编辑这个文件来提供翻译。

po文件结构解析

打开 django.po 文件，你会看到类似如下的内容：

#: path/to/template.html:10
msgid "Hello, world!"
msgstr ""

msgid：原始字符串（需要翻译的文本）。
msgstr：翻译后的字符串（留空表示未翻译）。
注释行（以 #: 开头）指示字符串的来源位置，帮助定位。

如何编辑po文件

使用文本编辑器：如VS Code、Sublime Text或任何纯文本编辑器打开 .po 文件。
填写翻译：在每个 msgstr 后面输入翻译内容。例如：
```
msgid "Hello, world!"
msgstr "你好，世界！"
```
保存文件：编辑完成后，保存更改。

工具推荐

对于大型项目，可以使用专门工具如 Poedit（免费开源）来简化编辑过程，它提供图形界面和自动翻译建议。

第3步：编译翻译文件（生成mo文件）

编辑完 .po 文件后，需要将其编译为 .mo 文件（Machine Object文件），这是Django运行时使用的二进制格式，提高性能。

运行compilemessages命令

在项目根目录下，运行以下命令：
```
django-admin compilemessages
```
这会将所有 .po 文件编译为对应的 .mo 文件，保存在同一目录（如 locale/zh_Hans/LC_MESSAGES/django.mo）。

验证编译

编译后，检查 .mo 文件是否生成。Django在运行时会自动加载这些文件来应用翻译。

第4步：模板与代码中的翻译语法应用

现在翻译文件已准备好，下一步是在模板和Python代码中使用翻译语法来标记字符串。

在模板中使用翻译

Django模板提供两种主要方式：

使用 {% trans %} 标签：适合短字符串。

<!-- 在模板文件中，如 index.html -->
<h1>{% trans "Welcome to our site!" %}</h1>

使用 {% blocktrans %} 标签：适合包含变量的长字符串。

{% blocktrans with user_name=user.username %}
  Hello, {{ user_name }}! Welcome back.
{% endblocktrans %}

确保在模板顶部加载翻译标签：

{% load i18n %}

在Python代码中使用翻译

在视图、模型或其他Python文件中，使用 gettext() 函数或其别名 _()。

导入翻译函数：

from django.utils.translation import gettext as _

标记字符串：

def my_view(request):
    message = _("This is a translated message.")
    return HttpResponse(message)

在运行 makemessages 命令时，这些字符串会被自动提取到 .po 文件中。

翻译语法注意事项

字符串格式：避免在翻译字符串中使用复杂逻辑；如果需要变量，使用 blocktrans 标签或Python的字符串格式化。
复数形式：Django支持复数翻译，使用 ngettext() 函数，但本教程限于基础，可后续深入学习。

第5步：示例项目演示

让我们通过一个简单示例来巩固所学。假设你有一个Django项目，包含以下内容：

项目结构：

myproject/
    manage.py
    myapp/
        views.py
        templates/
            home.html
    locale/
        zh_Hans/LC_MESSAGES/
            django.po
            django.mo

在 views.py 中：

from django.shortcuts import render
from django.utils.translation import gettext as _

def home(request):
    greeting = _("Hello from Django 6!")
    return render(request, 'home.html', {'greeting': greeting})

在 home.html 模板中：

{% load i18n %}
<!DOCTYPE html>
<html>
<head>
    <title>{% trans "Home Page" %}</title>
</head>
<body>
    <h1>{{ greeting }}</h1>
    <p>{% trans "This is a simple translation example." %}</p>
</body>
</html>

步骤回顾：
- 运行 makemessages -l zh_Hans 提取字符串到 django.po。
- 编辑 django.po，填写中文翻译。
- 运行 compilemessages 编译为 django.mo。
- 启动开发服务器（python manage.py runserver），访问页面应显示中文内容。

总结与最佳实践

定期更新翻译：每当添加新字符串时，重新运行 makemessages 和 compilemessages。
使用工具辅助：如Poedit或在线翻译平台来管理大型翻译项目。
测试翻译：在开发过程中切换语言设置（在 settings.py 中设置 LANGUAGE_CODE）来验证翻译效果。
性能优化：.mo 文件是编译后的二进制格式，比 .po 文件加载更快，确保在部署前编译。

通过本教程，你应该已经掌握了Django 6中翻译文件处理的基础。从提取字符串到应用翻译，这个过程虽然步骤多，但一旦熟悉，就能轻松为应用添加多语言支持。继续实践，探索更高级的国际化功能，如日期、数字格式化和复数处理！

教程结束。希望这篇指南帮助你快速上手Django翻译文件处理。如果有问题，参考Django官方文档或社区论坛获取更多支持。

上一章 13.1 国际化基础配置

下一章 13.3 本地化配置