翻译

为翻译者提供注释

如果你想为翻译者提供一些翻译字段的提示，你可以添加以 Translators 为前缀的注释。例如：

def my_view(request):
    # Translators: This message appears on the home page only
    output = gettext("Welcome to my site.")

这个注释将出现在 .po 文件中与所翻译词条相关的词条下方，并且也应该由大部分翻译工具显示。

#. Translators: This message appears on the home page only
# path/to/python/file.py:123
msgid "Welcome to my site."
msgstr ""

这个办法在模板里也同样适用。查看 模板内对翻译的注释 来获取更多详情。

上下文标记

一些词组有很多不同含义，比如 "May" ，它指五月或者表示一个动词。为了使翻译者在不同上下文中正确翻译这些词组，可以使用 django.utils.translation.pgettext() 函数，或者如果字符串需要复数形式的话，可以使用 django.utils.translation.npgettext() 函数。两者都使用上下文字符串作为第一个变量。

在生成的 .po 文件中，字符串将会频繁出现，因为相同字符串 ( 上下文将在 msgctxt 行上显示) 有不同的上下文标记，所以允许翻译者为每个字符串给出不同翻译。

例如：

from django.utils.translation import pgettext

month = pgettext("month name", "May")

或者：

from django.db import models
from django.utils.translation import pgettext_lazy

class MyThing(models.Model):
    name = models.CharField(help_text=pgettext_lazy(
        'help text for MyThing model', 'This is the help text'))

将以下方形式出现在 .po 文件中：

msgctxt "month name"
msgid "May"
msgstr ""

上下文标记也由 translate 和 blocktranslate 模板标签支持。

惰性翻译

当访问值而不是调用它们时，使用 django.utils.translation 中翻译函数的惰性版本 (在名称中加入 lazy 前缀来识别) 来延迟翻译字符串。

这些函数存储对字符串的惰性引用 —— 并非真实的翻译。当在字符串上下文里使用字符串时，才会翻译。比如模板渲染。

当对这些函数的调用位于模块加载时执行的代码路径中时，这一点非常重要。

在定义模型、表单和模型表单的时候，很容易遇见这种情况，因为 Django 已经实现了这些，所以它们的字段实际是类级别的属性。因此，请确保以下情况下使用惰性翻译：

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_('This is the help text'))

    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('my things')

from django.contrib import admin
from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

    @admin.display(description=_('Is it a mouse?'))
    def is_mouse(self):
        return self.kind.type == MOUSE_TYPE

JavaScriptCatalog 视图

class JavaScriptCatalog

一个视图，该视图生成一个 JavaScript 代码库，该库带有一个模仿 gettext 界面的函数，外加一个翻译字符串的数组。

属性

domain

翻译域包含要添加到视图输出中的字符串。默认为 'djangojs' 。

packages

已安装的应用程序的程序名列表。这些 app 应包含一个 locale 目录。所有这些目录加上 LOCALE_PATHS  里的目录会合并到一个目录里。默认是 None ，意味着在 JavaScript 输出中提供所有来自 INSTALLED_APPS 的可用翻译。

默认值实例 ：

from django.views.i18n import JavaScriptCatalog

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

自定义包实例 ：

urlpatterns = [
    path('jsi18n/myapp/',
         JavaScriptCatalog.as_view(packages=['your.app.label']),
         name='javascript-catalog'),
]

如果你的根 URLconf 使用 i18n_patterns() ，JavaScriptCatalog 也必须被 i18n_patterns() 包装，这样目录才会被正确的生成。

i18n_patterns() 实例：

from django.conf.urls.i18n import i18n_patterns

urlpatterns = i18n_patterns(
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
)

后面出现的 packages 参数比前面出现的参数优先级更高。在相同文字出现冲突翻译的时候，这点很重要。

如果你使用多个 JavaScriptCatalog 视图，并且它们中的某些视图定义了相同的字符串，那么最后加载的目录中的字符串拥有优先级。

set_language 重定向试图

set_language(request)

方便起见，Django 附带了一个视图 django.views.i18n.set_language() ，它可以设置用户语言首选项，并且重定向到一个给定的URL，或者默认情况下，会返回到上一页。

要激活这个视图，需要在你的 URLconf 中添加下面这行代码：

path('i18n/', include('django.conf.urls.i18n')),

（注意这个例子会使视图在 /i18n/setlang/ 下可用。）

视图期望通过 POST 方法调用，并在请求中设置 language 参数。如果 session 支持是可用的，视图会在用户的 session 中保存语言选择。它也会将语言选择保存在默认名为 django_language （名称可以通过 LANGUAGE_COOKIE_NAME 设置改变）的 cookie 中。

在设置语言选择后，Django 会检查 POST 或 GET 数据中的 next 参数。如果找到这个参数并且 Django 认为它是一个安全的链接（也就是说它不指向其他主机并使用安全模式），将会重定向到这个链接。否则，Django 可能会重定向到 Referer header 里的 URL，如果没设置这个 URL，则会跳转到 / ，这取决于请求的性质。

• 如果请求接受 HTML 内容（基于其 Accept HTTP头），将始终执行回退。
• 如果请求不接受 HTML，只有在设置了 next 参数的情况下才会进行回退。否则将返回 204 状态码（无内容）。

这里是一个模板代码的例子：

{% load i18n %}

<form action="{% url 'set_language' %}" method="post">{% csrf_token %}
    <input name="next" type="hidden" value="{{ redirect_to }}">
    <select name="language">
        {% get_current_language as LANGUAGE_CODE %}
        {% get_available_languages as LANGUAGES %}
        {% get_language_info_list for LANGUAGES as languages %}
        {% for language in languages %}
            <option value="{{ language.code }}"{% if language.code == LANGUAGE_CODE %} selected{% endif %}>
                {{ language.name_local }} ({{ language.code }})
            </option>
        {% endfor %}
    </select>
    <input type="submit" value="Go">
</form>

在这个例子中，Django 会在 redirect_to 变量中查找用户将要重定向的网址。

显式设置语言

你可能想显式地为当前会话设置语言。例如，可能是从另一个系统检索用户的语言偏好。你已经了解了 django.utils.translation.activate() 。这只适用于当前进程。要将整个会话的语言保留在 cookie 中，请在响应上设置 LANGUAGE_COOKIE_NAME ：

from django.conf import settings
from django.http import HttpResponse
from django.utils import translation
user_language = 'fr'
translation.activate(user_language)
response = HttpResponse(...)
response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)

通常你想同时使用这两者：django.utils.translation.activate() 改变这个线程的语言，并设置cookie使此首选项在以后的请求中保持不变。

Django 翻译的特性

Django 翻译机制使用 Python 自带的标准 gettext 模块。如果你知道 gettext ，你可能注意到了 Django 翻译的这些特性：

• 字符串域为 django 或 djangojs 。这个字符串域用来区分在相同消息文件库(message-file library,通常为 /usr/share/locale/ )中存有数据的不同项目。django 域被用于 Python和模板翻译字符串，以及加载到全局翻译目录。djangojs 域只用于 JavaScript 的翻译目录来确保它们尽可能小。
• Django 不会单独使用 xgettext 。它在 xgettext 和 msgfmt 周围使用 Python 装饰器。这主要是为了方便。

Django 如何发现语言偏好

一旦你准备好了翻译——或者，如果你想使用Django自带的翻译——那么你需要激活你的项目的翻译。

在后台，Django 有一个非常灵活的模型来决定使用哪一种语言——在全局使用，还是特定用户使用，还是二者都有。

在全局范围内设置语言偏好，需要设置 LANGUAGE_CODE 。Django 使用这个语言作为默认翻译 —— 如果通过 locale 中间件所使用的方法之一没有找到匹配的翻译，那么这是最后的尝试（见下文）。

如果你指向用你的母语运行 Django ，那么你需要做的就是设置 LANGUAGE_CODE 并确保存在相应的消息文件及其编译版本 (.mo) 。

如果你想让每个独立用户指定他们想要的语言，则还需要使用 LocaleMiddleware 。LocaleMiddleware 可以基于请求中的数据启用语言选择。它为每个用户定制内容。

要使用 LocaleMiddleware，请在你的 MIDDLEWARE 配置中添加 'django.middleware.locale.LocaleMiddleware'。因为中间件的顺序很重要，所以要遵循这些准则。

• 确保它是最先安装的中间件之一。
• 它应该在 SessionMiddleware 之后，因为 LocaleMiddleware 使用会话数据。而且它应该在 CommonMiddleware 之前，因为 CommonMiddleware 需要激活的语言来解析请求的 URL。
• 如果你使用 CacheMiddleware，把 LocaleMiddleware 放在它之后。

例如，你的 MIDDLEWARE 可能看起来像这样：

MIDDLEWARE = [
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
]

（关于中间件的更多信息，请参见 中间件文档。）

LocaleMiddleware 试图通过以下算法来确定用户的语言偏好。

• 首先，它在请求的URL中寻找语言前缀。 只有当你在你的根 URLconf 中使用 i18n_patterns 函数时，才会这样做。参见 国际化：在 URL 模式中 了解更多关于语言前缀和如何国际化 URL 模式的信息。

• 如果失败，它将查找 cookie。

  所使用的 cookie 的名称由 LANGUAGE_COOKIE_NAME 设定。（默认名称是 django_language）。

• 如果失败了，它将查看 Accept-Language HTTP 头。这个头由你的浏览器发送，并告诉服务器你喜欢哪种语言，按优先级排序。Django 会尝试每一种语言，直到找到可用的翻译。

• 如果不行，则使用全局 LANGUAGE_CODE 设置。

注意：

• 在每一个地方，语言偏好都应该是标准的 语言格式，作为一个字符串。例如，巴西葡萄牙语是 pt-br。

• 如果基本语言可用，但指定的子语言不可用，Django 就使用基本语言。例如，如果用户指定了 de-at （奥地利德语），但 Django 只有 de 可用，Django 就使用 de。

• 只有 LANGUAGES 设置中列出的语言才能被选择。如果你想将语言选择限制在所提供的语言子集中（因为你的应用程序没有提供所有这些语言），请将 LANGUAGES 设置为语言列表。例如：

  LANGUAGES = [
      ('de', _('German')),
      ('en', _('English')),
  ]

  这个例子将可供自动选择的语言限制为德语和英语（以及任何子语言，如 de-ch 或 en-us）。

• 如果你定义了一个自定义的 LANGUAGES 设置，就像上一弹所解释的那样，你可以将语言名称标记为翻译字符串——但要使用 gettext_lazy() 而不是 gettext() 来避免循环导入。

  以下是一个实例配置文件:

  from django.utils.translation import gettext_lazy as _
  
  LANGUAGES = [
      ('de', _('German')),
      ('en', _('English')),
  ]

一旦 LocaleMiddleware 确定了用户的偏好，它就会将这个偏好作为 request.LANGUAGE_CODE 提供给每一个 HttpRequest。在你的视图代码中可以随意读取这个值。下面是一个例子：

from django.http import HttpResponse

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian German.")
    else:
        return HttpResponse("You prefer to read another language.")

注意，静态（无中间件）翻译时，语言在 settings.LANGUAGE_CODE 中，而动态（中间件）翻译时，语言在 request.LANGUAGE_CODE 中。

Django 如何发现翻译

在运行时，Django 会在内存中建立一个统一的字面翻译目录。为了达到这个目的，它通过以下算法来查找翻译，关于它检查不同文件路径的顺序来加载编译的 消息文件 （.mo），以及同一字面意义的多个翻译的优先级。

1. LOCALE_PATHS 中列出的目录优先级最高，先出现的比后出现的优先级高。
2. 然后，它会在 INSTALLED_APPS 中列出的每个已安装的应用程序中寻找并使用是否存在 locale 目录。 先出现的比后出现的优先级高。
3. 最后，在 django/conf/locale 中使用 Django 提供的基础翻译作为后备。

在所有情况下，包含译文的目录名称应使用 locale name 符号来命名，如 de、pt_BR、es_AR 等。未翻译的地域语言变体字符串使用通用语言的翻译。例如，未翻译的 pt_BR 字符串使用 pt 翻译。

这样，你可以编写包含自己翻译的应用程序，你可以在你的项目中覆盖基础翻译。或者，你可以用几个应用程序构建一个大项目，并将所有翻译放到一个大的通用消息文件中，具体到你正在编写的项目。这是你的选择。

所有的消息文件库的结构都是一样的。它们是：

• 配置文件的 LOCALE_PATHS 中列出的所有路径都会被搜索到 <language>/LC_MESSAGES/django.(po|mo)
• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

为了创建消息文件，你使用 django-admin makemessages 工具。并使用 django-admin compilemessages 来生成二进制的 .mo 文件，这些文件被 gettext 使用。

你也可以运行 django-admin compilemessages --settings=path.to.settings 使编译器处理你 :settings:`LOCALE_PATHS` 设置中的所有目录。