转载:http://www.iteedu.com/webtech/python/djangocn2/chapter19.php
Django诞生于美国中部堪萨斯的劳伦斯,距美国的地理中心不到40英里。 像大多数开源项目一样,Djano社区逐渐开始包括来自全球各地的许多参与者。 鉴于Django社区逐渐变的多样性,国际化和本地化逐渐变的很重要。 由于很多开发者对这些措辞比较困惑,所以我们将简明的定义一下它们。
国际化* 是指为了该软件在任何地区的潜在使用而进行程序设计的过程。 它包括了为将来翻译而标记的文本(比如用户界面要素和错误信息等)、日期和时间的抽象显示以便保证不同地区的标准得到遵循、为不同时区提供支持,并且一般确保代码中不会存在关于使用者所在地区的假设。 您会经常看到国际化被缩写为“I18N”(18表示Internationlization这个单词首字母I和结尾字母N之间的字母有18个)。
本地化* 是指使一个国际化的程序为了在某个特定地区使用而进行实际翻译的过程。 有时,本地化缩写为 L10N 。
Django本身是完全国际化了的,所有的字符串均因翻译所需而被标记,并且设定了与地域无关的显示控制值,如时间和日期。 Django是带着40个不同的本地化文件发行的。 即使您的母语不是英语,Django也很有可能已经被翻译为您的母语了。
这些本地化文件所使用的国际化框架同样也可以被用在您自己的代码和模板中。
简要地说,您只需要添加少量的异常分支指令到您的Python代码和模板中。 这些异常分支指令被称为* 翻译字符串* 。它们告诉Django:这段文本应被翻译为终端用户指定的语言,如果这种语言的译文可以提供的话。
Django会根据用户的语言偏好,在线地运用这些异常分支指令去翻译Web应用程序。
本质上来说,Django做两件事情:
它让开发者和模板的作者指定他们的应用程序的哪些部分应该被翻译。
Django根据用户的语言偏好来翻译Web应用程序。
备注:
Django的翻译机制是使用 GNU gettext (http://www.gnu.org/software/gettext/),具体为Python自带的标准模块 gettext 。
如果您不需要国际化:
Django的国际化异常分支指令是默认开启的,这可能会给Django的运行增加一点点开销。 如果您不需要国际化支持,那么您可以在您的设置文件中设置 USE_I18N = False 。 如果 USE_I18N 被设为 False ,那么Django会进行一些优化,而不加载国际化支持机制。
您也可以从您的 TEMPLATE_CONTEXT_PROCESSORS 设置中移除 'django.core.context_processors.i18n' 。
对你的Django应用进行国际化的三个步骤:
第一步:在你的python代码和模板中嵌入待翻译的字符串。
第二步:把那些字符串翻译成你要支持的语言
第三步:在你的django settings文件中激活做要地区的中间件
我们将详细地对以上步骤逐一进行描述。
1、如何指定待翻译字符串
翻译字符串指定这段需要被翻译的文本。 这些字符串可以出现在您的Python代码和模板中。 而标记出这些翻译字符串则是您的责任;系统仅能翻译出它所知道的东西。
在Python 代码中
标准翻译
使用函数 ugettext() 来指定一个翻译字符串。 作为惯例,使用短别名 _ 来引入这个函数以节省键入时间.
在下面这个例子中,文本 "Welcome to my site" 被标记为待翻译字符串:
from django.utils.translation import ugettext as _def my_view(request):
output = _("Welcome to my site.")
return HttpResponse(output)
显然,你也可以不使用别名来编码。 下面这个例子和前面两个例子相同:
from django.utils.translation import ugettextdef my_view(request):
output = ugettext("Welcome to my site.")
return HttpResponse(output)
翻译字符串对于语句同样有效。 下面这个例子等同前面一种
def my_view(request):
words = ['Welcome', 'to', 'my', 'site.']
output = _(' '.join(words))
return HttpResponse(output)
翻译对变量也同样有效。 这里是一个同样的例子:
def my_view(request):
sentence = 'Welcome to my site.'
output = _(sentence)
return HttpResponse(output)
(以上两个例子中,对于使用变量或计算值,需要注意的一点是Django的待翻译字符串检测工具, make-messages.py ,将不能找到这些字符串。 稍后,在 makemessages 中会有更多讨论。
你传递给 _() 或 gettext() 的字符串可以接受占位符,由Python标准命名字符串插入句法指定的。 例如:
def my_view(request, m, d):
output = _('Today is %(month)s %(day)s.') % {'month': m, 'day': d}
return HttpResponse(output)
这项技术使得特定语言的译文可以对这段文本进行重新排序。 比如,一段英语译文可能是 "Today is November 26." ,而一段西班牙语译文会是 "Hoy es 26 de Noviembre." 使用占位符(月份和日期)交换他们的位置。
为了这个原因,无论何时当你有多于一个单一参数时,你应当使用命名字符串插入(例如: %(day)s )来替代位置插入(例如: %s or %d ) 如果你使用位置插入的话,翻译动作将不能重新排序占位符文本。
标记字符串为不操作
使用 django.utils.translation.gettext_noop() 函数来标记一个不需要立即翻译的字符串。 这个串会稍后从变量翻译。
使用这种方法的环境是,有字符串必须以原始语言的形式存储(如储存在数据库中的字符串)而在最后需要被翻译出来,如当其在用户前显示出来时。
惰性翻译
使用 django.utils.translation.gettext_lazy() 函数,使得其中的值只有在访问时才会被翻译,而不是在 gettext_lazy() 被调用时翻译。
例如:要翻译一个模型的 help_text,按以下进行
from django.utils.translation import ugettext_lazyclass MyThing(models.Model):
name = models.CharField(help_text=ugettext_lazy('This is the help text'))
在这个例子中, ugettext_lazy() 将字符串作为惰性参照存储,而不是实际翻译。 翻译工作将在字符串在字符串上下文中被用到时进行,比如在Django管理页面提交模板时。
在Python中,无论何处你要使用一个unicode 字符串(一个unicode 类型的对象),您都可以使用一个 ugettext_lazy() 调用的结果。 一个ugettext_lazy()对象并不知道如何转换它自己到一个字节串。如果你尝试在一个期待字节串的地方使用它,事情将不会像期待的那样发生。 同样,你也不能在一个字节串中使用一个 unicode 字符串。所以,这同常规的Python行为是一致的。 例如:
# This is fine: putting a unicode proxy into a unicode string.
u"Hello %s" % ugettext_lazy("people")This will not work, since you cannot insert a unicode object
into a bytestring (nor can you insert our unicode proxy there)
"Hello %s" % ugettext_lazy("people")
如果你曾经见到到像"hello"这样的输出,你就尝试过了在一个字节串中插入ugettext_lazy()的结果。 在您的代码中,那是一个漏洞。
如果觉得 gettext_lazy 太过冗长,可以用 _ (下划线)作为别名,就像这样:
from django.utils.translation import ugettext_lazy as _class MyThing(models.Model):
name = models.CharField(help_text=_('This is the help text'))
在Django模型中总是无一例外的使用惰性翻译。 为了翻译,字段名和表名应该被标记。(否则的话,在管理界面中它们将不会被翻译) 这意味着即使在Meta类中直截了当的写verbose_nane和verbose_name_plural选项,也不看着模型的类名,对Django的默认的verbose_name和verbose_name_plural缺省决定进行回复。
from django.utils.translation import ugettext_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 = _('mythings')
复数的处理
使用django.utils.translation.ungettext()来指定以复数形式表示的消息。 例如:
from django.utils.translation import ungettextdef hello_world(request, count):
page = ungettext('there is %(count)d object',
'there are %(count)d objects', count) % {
'count': count,
}
return HttpResponse(page)
ngettext 函数包括三个参数: 单数形式的翻译字符串,复数形式的翻译字符串,和对象的个数(将以 count 变量传递给需要翻译的语言)。
模板代码
Django模板使用两种模板标签,且语法格式与Python代码有些许不同。 为了使得模板访问到标签,需要将 {% load i18n %} 放在模板最前面。
这个{% trans %}模板标记翻译一个常量字符串 (括以单或双引号) 或 可变内容:
{% trans "This is the title." %}
{% trans myvar %}
System Message: ERROR/3 (
Error in “cnid” directive: no content permitted.
.. cnid:: 73如果
System Message: WARNING/2 (
Explicit markup ends without a blank line; unexpected unindent.
noop 选项是当前的,变量查询还会取代但翻译会跳过。 当欠缺内容要求将来再翻译时,这很有用。
{% trans "myvar" noop %}
在一个带 {% trans %} 的字符串中,混进一个模板变量是不可能的。如果你的译文要求字符串带有变量(占位符placeholders),请使用 {% blocktrans %} :
{% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
使用模板过滤器来翻译一个模板表达式,需要在翻译的这段文本中将表达式绑定到一个本地变量中:
{% blocktrans with value|filter as myvar %}
This will have {{ myvar }} inside.
{% endblocktrans %}
如果需要在 blocktrans 标签内绑定多个表达式,可以用 and 来分隔:
{% blocktrans with book|title as book_t and author|title as author_t %}
This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}
为了表示单复数相关的内容,需要在 {% blocktrans %} 和 {% endblocktrans %} 之间使用 {% plural %} 标签来指定单复数形式,例如:
{% blocktrans count list|length as counter %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktrans %}
其内在机制是,所有的块和内嵌翻译调用相应的 gettext 或 ngettext 。
每一个RequestContext可以访问三个指定翻译变量:
{{ LANGUAGES }} 是一系列元组组成的列表,每个元组的第一个元素是语言代码,第二个元素是用该语言表示的语言名称。
作为一二字符串,LANGUAGE_CODE是当前用户的优先语言。 例如: en-us。(请参见下面的Django如何发现语言偏好)
LANGUAGE_BIDI就是当前地域的说明。 如果为真(True),它就是从右向左书写的语言,例如: 希伯来语,阿拉伯语。 如果为假(False),它就是从左到右书写的语言,如: 英语,法语,德语等。
如果你不用这个RequestContext扩展,你可以用3个标记到那些值:
{% get_current_language as LANGUAGE_CODE %}
{% get_available_languages as LANGUAGES %}
{% get_current_language_bidi as LANGUAGE_BIDI %}
这些标记亦要求一个 {% load i18n %} 。
翻译的hook在任何接受常量字符串的模板块标签内也是可以使用的。 此时,使用 _() 表达式来指定翻译字符串,例如:
{% some_special_tag ("Page not found") value|yesno:("yes,no") %}
在这种情况下,标记和过滤器两个都会看到已经翻译的字符串,所有它们并不需要提防翻译操作。
备注:
在这个例子中,翻译结构将放过字符串"yes,no",而不是单独的字符串"yes"和"no"。翻译的字符串将需要包括逗号以便过滤器解析代码明白如何分割参数。 例如, 一个德语翻译器可能会翻译字符串 "yes,no" 为 "ja,nein" (保持逗号原封不动)。
与惰性翻译对象一道工作
在模型和公用函数中,使用ugettext_lazy()和ungettext_lazy()来标记字符串是很普遍的操作。 当你在你的代码中其它地方使用这些对象时,你应当确定你不会意外地转换它们成一个字符串,因为它们应被尽量晚的转换(以便正确的地域生效) 这需要使用及个帮助函数。
拼接字符串: string_concat()
标准Python字符串拼接(''.join([...]) ) 将不会工作在包括惰性翻译对象的列表上。 作为替代,你可以使用django.utils.translation.string_concat(), 这个函数创建了一个惰性对象,其连接起它的内容 并且 仅当结果被包括在一个字符串中时转换它们为字符串 。 例如:
from django.utils.translation import string_concat...
name = ugettext_lazy(u'John Lennon')
instrument = ugettext_lazy(u'guitar')
result = string_concat([name, ': ', instrument])
System Message: ERROR/3 (
Error in “cnid” directive: no content permitted.
.. cnid:: 109在这种情况下,当
System Message: WARNING/2 (
Explicit markup ends without a blank line; unexpected unindent.
result 自己被用与一个字符串时, result 中的惰性翻译将仅被转换为字符串(通常在模板渲染时间)。
allow_lazy() 修饰符
Django提供很多功能函数(如:取一个字符串作为他们的第一个参数并且对那个字符串做些什么)。(尤其在 django.utils 中) 这些函数被模板过滤器像在其他代码中一样直接使用。
如果你写你自己的类似函数并且与翻译打交道,当第一个参数是惰性翻译对象是,你会面临“做什么”的难题。 因为你可能在视图之外使用这个函数(并且因此当前线程的本地设置将会不正确),所以你不想立即转换其为一个字符串。
象这种情况,请使用 django.utils.functional.allow_lazy() 修饰符。 它修改这个函数以便 if 作为第一个参数被一个惰性翻译调用, 这个函数的赋值会被延后直到它需要被转化为一个字符串为止。
例如:
from django.utils.functional import allow_lazydef fancy_utility_function(s, ...):
# Do some conversion on string 's'
# ...
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
allow_lazy() 装饰符 采用了另外的函数来装饰,以及一定量的,原始函数可以返回的特定类型的额外参数 (*args ) 。 通常,在这里包括 unicode 就足够了并且确定你的函数将仅返回Unicode字符串。
使用这个修饰符意味着你能写你的函数并且假设输入是合适的字符串,然后在末尾添加对惰性翻译对象的支持。
2、如何创建语言文件
当你标记了翻译字符串,你就需要写出(或获取已有的)对应的语言翻译信息。 这里就是它如何工作的。
地域限制
Django不会支持本地化你的应用到一个连它自己都还没被翻译的地域。 在这种情况下,它将忽略你的翻译文件。 如果你想尝试这个并且Django支持它,你会不可避免地见到这样一个混合体––参杂着你的译文和来自Django自己的英文。 如果你的应用需要你支持一个Django中没有的地域,你将至少需要做一个Django core的最小翻译。
消息文件
第一步,就是为一种语言创建一个信息文件。 一个信息文件是包含了某一语言翻译字符串和对这些字符串的翻译的一个文本文件。 信息文件以 .po 为后缀名。
Django中带有一个工具, bin/make-messages.py ,它完成了这些文件的创建和维护工作。 运行以下命令来创建或更新一个信息文件:
django-admin.py makemessages -l de
其中 de 是所创建的信息文件的语言代码。 在这里,语言代码是以本地格式给出的。 例如,巴西地区的葡萄牙语为 pt_BR ,澳大利亚地区的德语为 de_AT 。可查看 django/conf/locale 目录获取Django所支持的语言代码。
这段脚本应该在三处之一运行:
Django项目根目录
您Django应用的根目录。
django 根目录(不是Subversion检出目录,而是通过 $PYTHONPATH 链接或位于该路径的某处) 这仅和你为Django自己创建一个翻译时有关。
这段脚本遍历你的项目源树或你的应用程序源树并且提取出所有为翻译而被标记的字符串。 它在 conf/locale 目录下创建(或更新)了一个信息文件。
作为默认, django-admin.py makemessages 检测每一个有 .html 扩展名的文件。 以备你要重载缺省值,使用 --extension 或 -e 选项指定文件扩展来检测。
django-admin.py makemessages -l de -e txt
用逗号和(或)使用-e或--extension来分隔多项扩展项:
django-admin.py makemessages -l de -e html,txt -e xml
当创建JavaScript翻译目录时,你需要使用特殊的Django域:not -e js 。
没有gettext?
如果没有安装 gettext 组件, make-messages.py 将会创建空白文件。 这种情况下,安装 gettext 组件或只是复制英语信息文件( conf/locale/en/LC_MESSAGES/django.po )来作为一个起点;只是一个空白的翻译信息文件而已。
工作在Windows上么?
如果你正在使用Windows,且需要安装GNU gettext共用程序以便 django-admin makemessages 可以工作,请参看下面Windows小节中gettext部分以获得更多信息。
.po 文件格式很直观。 每个 .po 文件包含一小部分的元数据,比如翻译维护人员的联系信息,而文件的大部分内容是简单的翻译字符串和对应语言翻译结果的映射关系的列表。
举个例子,如果Django应用程序包括一个 "Welcome to my site." 的待翻译字符串 ,像这样:
_("Welcome to my site.")
则django-admin.py makemessages将创建一个 .po 文件来包含以下片段的消息:
#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""
一个快速解释:
msgid 是在源文件中出现的翻译字符串。 不要做改动。
msgstr 是相应语言的翻译结果。 刚创建时它只是空字符串,此时就需要你来完成它。 注意不要丢掉语句前后的引号。
作为方便之处,每一个消息都包括:以 # 为前缀的一个注释行并且定位上边的msgid 行,文件名和行号。
对于比较长的信息也有其处理方法。 msgstr (或 msgid )后紧跟着的字符串为一个空字符串。 然后真正的内容在其下面的几行。 这些字符串会被直接连在一起。 同时,不要忘了字符串末尾的空格,因为它们会不加空格地连到一起。
................