gettext --- 多语种国际化服务¶

GNU gettext API¶

模块 gettext 定义了下列 API，这与 gettext API 类似。如果你使用该 API，将会对整个应用程序产生全局的影响。如果你的应用程序支持多语种，而语言选择取决于用户的语言环境设置，这通常正是你所想要的。而如果你正在本地化某个 Python 模块，或者你的应用程序需要在运行时切换语言，相反你或许想用基于类的API。

gettext.bindtextdomain(___domain, localedir=None)¶

将 ___domain 绑定到本地目录 localedir。 更具体地来说，模块 gettext 将使用路径 (在 Unix 系统中): localedir/language/LC_MESSAGES/___domain.mo 查找二进制 .mo 文件，此处对应地查找 language 的位置是环境变量 LANGUAGE, LC_ALL, LC_MESSAGES 和 LANG 中。

如果遗漏了 localedir 或者设置为 None，那么将返回当前 ___domain 所绑定的值 [1]

gettext.textdomain(___domain=None)¶

修改或查询当前的全局域。如果 ___domain 为 None，则返回当前的全局域，不为 None 则将全局域设置为 ___domain，并返回它。

gettext.gettext(message)¶

返回 message 的本地化翻译，依据当前的全局域、语言和语言区域目录。 本函数在局部命名空间中通常包含别名 _() (参见下面的示例)。

gettext.dgettext(___domain, message)¶

与 gettext() 类似，但在指定的 ___domain 中查找 message。

gettext.ngettext(singular, plural, n)¶

与 gettext() 类似，但考虑了复数形式。如果找到了翻译，则将 n 代入复数公式，然后返回得出的消息（某些语言具有两种以上的复数形式）。如果未找到翻译，则 n 为 1 时返回 singular，为其他数时返回 plural。

复数公式取自编目头文件。它是 C 或 Python 表达式，有一个自变量 n，该表达式计算的是所需复数形式在编目中的索引号。关于在 .po 文件中使用的确切语法和各种语言的公式，请参阅 GNU gettext 文档 。

gettext.dngettext(___domain, singular, plural, n)¶

与 ngettext() 类似，但在指定的 ___domain 中查找 message。

gettext.pgettext(context, message)¶

gettext.dpgettext(___domain, context, message)¶

gettext.npgettext(context, singular, plural, n)¶

gettext.dnpgettext(___domain, context, singular, plural, n)¶

与前缀中没有 p 的相应函数类似（即 gettext(), dgettext(), ngettext(), dngettext() ），但是仅翻译给定的 message context。

Added in version 3.8.

请注意 GNU gettext 还定义了一个 dcgettext() 方法，但它被认为并不实用因此目前尚未实现它。

这是该 API 的典型用法示例:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))

基于类的 API¶

与 GNU gettext API 相比，gettext 模块的基于类的API 提供了更多的灵活性和便利性。 这是本地化 Python 应用程序和模块的推荐方式。 gettext 定义了一个 GNUTranslations 类，它实现了对 GNU .mo 格式文件的解析，并且具有用于返回字符串的方法。 本类的实例也可以将自身作为函数 _() 安装到内置命名空间中。

gettext.find(___domain, localedir=None, languages=None, all=False)¶

本函数实现了标准的 .mo 文件搜索算法。它接受一个 ___domain，它与 textdomain() 接受的域相同。可选参数 localedir 与 bindtextdomain() 中的相同。可选参数 languages 是多条字符串的列表，其中每条字符串都是一种语言代码。

如果没有传入 localedir，则使用默认的系统语言环境目录。 [2] 如果没有传入 languages，则搜索以下环境变量：LANGUAGE、LC_ALL、LC_MESSAGES 和 LANG。从这些变量返回的第一个非空值将用作 languages 变量。环境变量应包含一个语言列表，由冒号分隔，该列表会被按冒号拆分，以产生所需的语言代码字符串列表。

find() 将扩展并规范化 language，然后遍历它们，搜索由这些组件构建的现有文件:

localedir/language/LC_MESSAGES/___domain.mo

find() 返回找到类似的第一个文件名。如果找不到这样的文件，则返回 None。如果传入了 all，它将返回一个列表，包含所有文件名，并按它们在语言列表或环境变量中出现的顺序排列。

gettext.translation(___domain, localedir=None, languages=None, class_=None, fallback=False)¶

根据 ___domain, localedir 和 languages 返回一个 *Translations 实例，它们将首先被传给 find() 以获取由所关联的 .mo 文件路径组成的列表。 具有相同 .mo 文件名的实例会被缓存。 如果提供了 class_ 则它将是被实例化的类，否则将是 GNUTranslations。 该类的构造器必须接受一个 file object 参数。

如果找到多个文件，后找到的文件将用作先前文件的替补。为了设置替补，将使用 copy.copy() 从缓存中克隆每个 translation 对象。实际的实例数据仍在缓存中共享。

如果 .mo 文件未找到，且 fallback 为 false（默认值），则本函数引发 OSError 异常，如果 fallback 为 true，则返回一个 NullTranslations 实例。

在 3.3 版本发生变更: 过去触发的 IOError，现在是 OSError 的别名。

在 3.11 版本发生变更: codeset 形参已被移除。

gettext.install(___domain, localedir=None, *, names=None)¶

这将在 Python 的内置命名空间中安装 _() 函数，基于传给 translation() 函数的 ___domain 和 localedir。

names 参数的信息请参阅 translation 对象的 install() 方法的描述。

如下所示，通常是将字符串包裹在对 _() 函数的调用中，以标记应用程序中待翻译的字符串，就像这样:

print(_('This string will be translated.'))

为了方便，可将 _() 函数安装在 Python 的内置命名空间中，这样就可以在应用程序的所有模块中轻松地访问它。

在 3.11 版本发生变更: names 现在是仅限关键字形参。

import gettext
cat = gettext.Catalog(___domain, localedir)
_ = cat.gettext
print(_('hello world'))

国际化 (I18N) 你的程序和模块¶

国际化 (I18N) 是指使程序可切换多种语言的操作。本地化 (L10N) 是指程序的适配能力，一旦程序被国际化，就能适配当地的语言和文化习惯。为了向 Python 程序提供不同语言的消息，需要执行以下步骤：

1. 准备程序或模块，将可翻译的字符串特别标记起来

2. 在已标记的文件上运行一套工具，用来生成原始消息编目

3. 创建消息编目的不同语言的翻译

4. 使用 gettext 模块，以便正确翻译消息字符串

为了准备代码以实现 I18N，你需要查看文件中的所有字符串。 任何需要翻译的字符串都应在 _('...') 中包含它来进行标记 --- 即调用函数 _。 例如:

filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)

在这个例子中，字符串 'writing a log message' 被标记为待翻译，而字符串 'mylog.txt' 和 'w' 没有被标记。

有一些工具可以将待翻译的字符串提取出来。 原版的 GNU gettext 仅支持 C 或 C++ 源代码，但其扩展版 xgettext 可以扫描多种语言的代码，包括 Python 在内，来找出标记为可翻译的字符串。 Babel 是一个包括了可用于提取并编译消息编目的 pybabel 脚本的 Python 国际化库。 François Pinard 的 xpot 程序也能完成类似的工作并可在他的 po-utils 包 中获取。

（Python 还包括了这些程序的纯 Python 版本，称为 pygettext.py 和 msgfmt.py，某些 Python 发行版已经安装了它们。pygettext.py 类似于 xgettext，但只能理解 Python 源代码，无法处理诸如 C 或 C++ 的其他编程语言。pygettext.py 支持的命令行界面类似于 xgettext，查看其详细用法请运行 pygettext.py --help。msgfmt.py 与 GNU msgfmt 是二进制兼容的。有了这两个程序，可以不需要 GNU gettext 包来国际化 Python 应用程序。）

xgettext、pygettext 或类似工具生成的 .po 文件就是消息编目。它们是结构化的人类可读文件，包含源代码中所有被标记的字符串，以及这些字符串的翻译的占位符。

然后把这些 .po 文件的副本交给各个人工译者，他们为所支持的每种自然语言编写翻译。译者以 <语言名称>.po 文件的形式发送回翻译完的某个语言的版本，将该文件用 msgfmt 程序编译为机器可读的 .mo 二进制编目文件。gettext 模块使用 .mo 文件在运行时进行实际的翻译处理。

如何在代码中使用 gettext 模块取决于国际化单个模块还是整个应用程序。接下来的两节将讨论每种情况。

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext

import gettext
gettext.install('myapplication')

import gettext
gettext.install('myapplication', '/usr/share/locale')

import gettext

lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])

# 从使用语言 1 开始
lang1.install()

# ... 过一段时间后，用户选择了语言 2
lang2.install()

# ... 再过一段时间后，用户选择了语言 3
lang3.install()

animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)

def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
           _('rat'),
           _('penguin'),
           _('python'), ]

del _

# ...
for a in animals:
    print(_(a))

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))

致谢¶

以下人员为创建此模块贡献了代码、反馈、设计建议、早期实现和宝贵的经验：

• Peter Funk

• James Henstridge

• Juan David Ibáñez Palomar

• Marc-André Lemburg

• Martin von Löwis

• François Pinard

• Barry Warsaw

• Gustavo Niemeyer

备注