编辑“︁Django国际化”︁

= Django国际化 =

== 介绍 ==
'''Django国际化'''（Internationalization，简称i18n）是指将Django应用程序适配为支持多种语言和区域设置的过程。这一功能使得开发者能够为全球用户提供本地化的内容，包括翻译文本、日期/时间格式、数字格式等。Django通过内置的翻译系统（translation system）简化了这一过程。

国际化通常涉及三个主要方面：
* '''文本翻译'''：将界面中的字符串转换为目标语言。
* '''本地化格式'''：根据地区调整日期、时间、数字的显示方式。
* '''时区处理'''：正确处理用户所在时区的时间显示。

== 基本配置 ==
在Django项目中启用国际化功能，需在<code>settings.py</code>中进行以下配置：

<syntaxhighlight lang="python">
# settings.py

# 启用国际化
USE_I18N = True

# 启用本地化格式（如日期、数字）
USE_L10N = True

# 设置支持的语言
LANGUAGES = [
    ('en', 'English'),
    ('zh-hans', '简体中文'),
    ('es', 'Spanish'),
]

# 设置默认语言
LANGUAGE_CODE = 'en'

# 指定翻译文件所在目录
LOCALE_PATHS = [
    os.path.join(BASE_DIR, 'locale'),
]
</syntaxhighlight>

=== 中间件配置 ===
Django的<code>LocaleMiddleware</code>负责根据用户请求确定语言偏好。需将其添加到<code>MIDDLEWARE</code>中：

<syntaxhighlight lang="python">
MIDDLEWARE = [
    ...
    'django.middleware.locale.LocaleMiddleware',
    ...
]
</syntaxhighlight>

== 标记可翻译文本 ==
在Django模板和Python代码中，需使用特定的函数标记需要翻译的文本。

=== 在模板中 ===
在模板中，使用<code>{% trans %}</code>标签或<code>{% blocktrans %}</code>块标记可翻译内容：

<syntaxhighlight lang="django">
<!-- 简单文本翻译 -->
{% load i18n %}
<h1>{% trans "Welcome to our website!" %}</h1>

<!-- 带变量的翻译 -->
<p>{% blocktrans with username=user.username %}Hello, {{ username }}!{% endblocktrans %}</p>
</syntaxhighlight>

=== 在Python代码中 ===
在视图或其他Python代码中，使用<code>gettext()</code>（通常别名为<code>_()</code>）函数：

<syntaxhighlight lang="python">
from django.utils.translation import gettext as _

def my_view(request):
    output = _("Welcome to our site!")
    return HttpResponse(output)
</syntaxhighlight>

== 提取翻译字符串 ==
Django提供了<code>makemessages</code>命令来提取所有标记为可翻译的字符串到<code>.po</code>文件中：

<syntaxhighlight lang="bash">
# 提取所有语言
django-admin makemessages -l zh_Hans
django-admin makemessages -l es

# 更新已有翻译
django-admin makemessages -a
</syntaxhighlight>

生成的<code>.po</code>文件位于<code>locale/</code>目录下，结构如下：

<mermaid>
graph TD
    locale/
    ├── zh_Hans/
    │   └── LC_MESSAGES/
    │       ├── django.po
    │       └── django.mo
    └── es/
        └── LC_MESSAGES/
            ├── django.po
            └── django.mo
</mermaid>

== 编译翻译文件 ==
翻译完成后，需将<code>.po</code>文件编译为二进制<code>.mo</code>文件：

<syntaxhighlight lang="bash">
django-admin compilemessages
</syntaxhighlight>

== 语言切换 ==
Django提供了多种方式让用户切换语言：

=== URL前缀 ===
在<code>urls.py</code>中配置：

<syntaxhighlight lang="python">
from django.conf.urls.i18n import i18n_patterns

urlpatterns = i18n_patterns(
    path('', views.home, name='home'),
    prefix_default_language=False,
)
</syntaxhighlight>

这样URL会变为<code>/en/</code>、<code>/zh-hans/</code>等形式。

=== 通过视图切换 ===
可以创建一个语言切换视图：

<syntaxhighlight lang="python">
from django.http import HttpResponseRedirect
from django.utils.translation import activate

def set_language(request, language_code):
    activate(language_code)
    request.session[settings.LANGUAGE_SESSION_KEY] = language_code
    return HttpResponseRedirect(request.META.get('HTTP_REFERER', '/'))
</syntaxhighlight>

== 高级主题 ==

=== 复数形式 ===
Django支持处理不同复数形式的翻译：

<syntaxhighlight lang="python">
from django.utils.translation import ngettext

count = 5
message = ngettext(
    'There is %(count)d apple.',
    'There are %(count)d apples.',
    count
) % {'count': count}
</syntaxhighlight>

=== 本地化格式 ===
Django会自动根据当前语言环境格式化日期、数字等：

<syntaxhighlight lang="django">
{% load l10n %}

<!-- 本地化日期 -->
{{ value|date }}

<!-- 本地化数字 -->
{{ value|floatformat }}
</syntaxhighlight>

=== JavaScript国际化 ===
对于前端内容，Django提供了JavaScript翻译功能：

1. 首先在视图中包含JavaScript翻译目录：
<syntaxhighlight lang="python">
from django.views.i18n import JavaScriptCatalog

urlpatterns = [
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
]
</syntaxhighlight>

2. 在模板中引入：
<syntaxhighlight lang="django">
<script src="{% url 'javascript-catalog' %}"></script>
</syntaxhighlight>

3. 在JavaScript中使用：
<syntaxhighlight lang="javascript">
const translated = gettext('This text will be translated');
</syntaxhighlight>

== 实际案例 ==
假设我们有一个多语言博客系统：

1. 在<code>models.py</code>中定义可翻译字段：
<syntaxhighlight lang="python">
from django.db import models
from django.utils.translation import gettext_lazy as _

class BlogPost(models.Model):
    title = models.CharField(_('Title'), max_length=200)
    content = models.TextField(_('Content'))
    created_at = models.DateTimeField(_('Created at'), auto_now_add=True)
</syntaxhighlight>

2. 在模板中显示本地化内容：
<syntaxhighlight lang="django">
{% load i18n l10n %}

<article>
    <h1>{{ post.title }}</h1>
    <div class="content">{{ post.content }}</div>
    <time datetime="{{ post.created_at|date:'c' }}">
        {% blocktrans with created_date=post.created_at|date %}Posted on {{ created_date }}{% endblocktrans %}
    </time>
</article>

<div class="language-switcher">
    <form action="{% url 'set_language' %}" method="post">
        {% csrf_token %}
        <select name="language">
            {% get_current_language as LANGUAGE_CODE %}
            {% get_available_languages as LANGUAGES %}
            {% for code, name in LANGUAGES %}
                <option value="{{ code }}" {% if code == LANGUAGE_CODE %}selected{% endif %}>
                    {{ name }}
                </option>
            {% endfor %}
        </select>
        <input type="submit" value="{% trans 'Switch' %}">
    </form>
</div>
</syntaxhighlight>

== 最佳实践 ==
1. '''尽早规划国际化'''：在项目初期就考虑国际化需求
2. '''保持字符串简洁'''：避免长而复杂的句子，便于翻译
3. '''避免拼接字符串'''：如<code>"Hello " + name + "!"</code>应改为<code>_("Hello %(name)s!") % {'name': name}</code>
4. '''测试所有语言'''：确保界面在不同语言下都能正常显示
5. '''考虑RTL语言'''：如阿拉伯语、希伯来语等从右向左书写的语言

== 常见问题 ==
'''Q: 为什么我的翻译没有生效？'''
A: 请检查：
1. 是否正确标记了可翻译字符串
2. 是否运行了<code>makemessages</code>和<code>compilemessages</code>
3. 翻译文件是否放在正确的<code>locale</code>目录
4. 浏览器是否发送了正确的<code>Accept-Language</code>头

'''Q: 如何处理动态内容翻译？'''
A: 对于用户生成内容，可以考虑：
1. 为每种语言保存不同版本的文本
2. 使用机器翻译API（如Google Translate）
3. 让用户自己提交不同语言的版本

== 总结 ==
Django国际化是一个强大的功能，允许开发者轻松创建多语言网站。通过合理使用翻译系统、本地化格式和语言切换功能，可以为全球用户提供更好的体验。虽然初始设置需要一些工作，但Django的工具链使得整个过程相对简单高效。

[[Category:后端框架]]
[[Category:Django]]
[[Category:Django模板系统]]