GNU gettext API

gettext模块定义了以下API，与GNU gettext的API。如果使用此API，则会影响整个应用程序的全局翻译。如果您的应用程序是单语的，那么这通常就是您想要的，语言的选择取决于您的用户的名称。如果要本地化Python模块，或者如果应用程序需要动态切换语言，则可能需要使用基于类的API .

gettext.bindtextdomain（domain, localedir=None）

将domain绑定到语言环境目录localedir。更具体地说，gettext将使用路径（在Unix上）查找给定域的二进制.mo文件：localedir/language/LC_MESSAGES/domain.mo，其中languages在环境变量LANGUAGE,LC_ALL, LC_MESSAGES和LANG中分别搜索

如果localedir被省略或None，则当前绑定为domain回复。[1]

gettext.bind_textdomain_codeset（domain, codeset=None）

绑定domain到codeset，更改lgettext(), ldgettext(), lngettext()和ldngettext()函数返回的字节字符串的编码。如果codeset被省略，则返回当前绑定.

gettext.textdomain（domain=None）

更改或查询当前的全局域。如果domain是None，则返回当前全局域，否则全局域设置为domain，返回

gettext.gettext//(message）

根据当前的globaldomain，language和locale目录返回message的本地化翻译。此函数通常在本地命名空间中别名为_()（参见下面的示例）.

gettext.dgettext（domain, message）

喜欢gettext()，但是在指定的domain.

gettext.ngettext（singular, plural, n）

看看信息像gettext()，但考虑复数形式。如果找到翻译，请将复数公式应用于n，并返回结果消息（somelanguages有两个以上的复数形式）。如果没有找到翻译，如果singular为1则返回n;返回plural否则

Plural公式取自目录标题。它是一个C或Pythonexpression有一个自由变量n;表达式求值为目录中复数的索引。请参阅GNU gettext文档，了解在.po文件中使用的精确语法以及各种语言的公式.

gettext.dngettext（domain, singular, plural, n）

喜欢 ngettext()，但在指定的domain.

gettext.lgettext（message）

gettext.ldgettext（domain, message）

gettext.lngettext（singular, plural, n）

gettext.ldngettext（domain, singular, plural, n）

相当于没有l字首（gettext(), dgettext(), ngettext()和dngettext()），但如果没有使用bind_textdomain_codeset().

警告

在Python 3中应该避免使用这些函数，因为它们返回了编码的字节。使用返回Unicode字符串的替代方法要好得多，因为大多数Python应用程序都希望将人类可读的文本操作为字符串而不是字节。此外，如果翻译的字符串存在编码问题，则可能会出现意外的与Unicode相关的异常。可能是l*()函数将在以后的Pythonversions中被弃用，因为它们存在固有的问题和限制.

注意GNU gettext 也定义了dcgettext()方法，但这被认为没用，所以它目前没有实现.

以下是此API的典型用法示例：

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

基于类的API

的基于类的APIgettext模块比GNU gettext API提供更多的灵活性和更大的便利性。它是本地化Python应用程序和模块的推荐途径。gettext定义实现GNU .moformatfiles，并具有返回字符串的方法。这个“翻译”类的实例也可以自己安装在内置的命名空间中作为函数_().

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()然后扩展和规范化语言，然后迭代它们，搜索现有文件由这些组件构成：

localedir/language/LC_MESSAGES/domain.mo

第一个这样的文件名由find()返回。如果没有找到这样的文件，则返回None。如果给出all，则返回所有文件名的列表，按照它们出现在语言列表或环境变量中的顺序.

gettext.translation (domain, localedir=None, languages=None, class_=None, fallback=False, codeset=None）

根据Translations和domain, localedir返回一个languages实例，首先传递给find()以获取相关的列表.mo文件路径。缓存具有相同.mo文件名的实例。实例化的实例是class_，否则GNUTranslations。类的构造函数必须使用单个文件对象参数。如果提供，codeset将改变用于编码lgettext()和lngettext()methods.

如果找到多个文件，则后面的文件将用作早期文件的后备。要允许设置后备，copy.copy()用于从缓存中克隆每个翻译对象;实际的实例数据仍然与缓存共享.

如果找不到.mo文件，这个函数会提升OSError如果fallback是假的（这是默认值），如果NullTranslations为真，则返回fallback实例.

在版本3.3中更改：IOError曾经被提升代替OSError.

gettext.install（domain, localedir=None, codeset=None, names=None）

这个安装功能_()在Python的内置命名空间中，基于domain, localedir和codeset传递给函数translation().

对于names参数，请参阅翻译对象的描述install() 方法。

如下所示，您通常会在应用程序中标记用于转换的字符串，通过将它们包装在对_()函数的调用中，如下所示：

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

为方便起见，您需要_()函数安装在Python’sbuiltins命名空间中，因此可以在你的应用程序的所有模块中轻松访问.

import gettextcat = gettext.Catalog(domain, localedir)_ = cat.gettextprint(_("hello world"))

国际化你的程序和模块

国际化（I18N）指的是操作通过该程序使多种语言成为可能。本地化（L10N）是指您的程序一旦国际化，就会适应当地语言和文化习惯。为了向您的Python程序提供多语言消息，您需要执行以下步骤：

1. 准备您的程序或模块通过专门标记可翻译的字符串
2. 在您标记的文件上运行一套工具来生成原始消息目录
3. 创建消息目录的语言特定翻译
4. 使用gettext模块以便正确翻译消息字符串

为了准备I18N的代码，你需要查看你文件中的所有字符串。任何需要翻译的字符串都应该用_("...")中的包装标记 – 也就是调用函数_()。例如：

filename = "mylog.txt"message = _("writing a log message")fp = open(filename, "w")fp.write(message)fp.close()

在这个例子中，字符串"writing a log message"被标记为翻译候选者，而字符串"mylog.txt"和"w"不是.

有一些工具可以提取用于翻译的字符串。原始GNU gettext 仅支持C或C ++源代码，但其扩展版本为 xgettext 扫描用多种语言编写的代码，包括Python，以查找标记为可译的字符串。Babel是一个Pythoninternationalization库，包含pybabel脚本提取和编译消息目录。FrançoisPinard的节目叫 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 包来国际化你的Pythonapplications。）

xgettext , pygettext ，和类似的工具生成.po作为消息目录的文件。它们是结构化的可读文件，包含源代码中的每个标记字符串，以及forsestrings的翻译版本的占位符.

这些副本.po然后将文件移交给为自己支持的自然语言编写翻译的个人翻译。他们将已完成的语言版本发送回<language-name>.po使用.mo msgfmt 程序将文件编译成机器可读的二进制目录文件。.mo使用gettext用于实际翻译处理的模块atrun-time.

你如何使用gettext代码中的模块取决于您是将单个模块还是整个应用程序进行国际化。接下来的两个部分将讨论每个案例.

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

import gettextgettext.install("myapplication")

import gettextgettext.install("myapplication", "/usr/share/locale")

import gettextlang1 = gettext.translation("myapplication", languages=["en"])lang2 = gettext.translation("myapplication", languages=["fr"])lang3 = gettext.translation("myapplication", languages=["de"])# start by using language1lang1.install()# ... time goes by, user selects language 2lang2.install()# ... more time goes by, user selects language 3lang3.install()

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

def _(message): return messageanimals = [_("mollusk"),           _("albatross"),           _("rat"),           _("penguin"),           _("python"), ]del _# ...for a in animals:    print(_(a))

def N_(message): return messageanimals = [N_("mollusk"),           N_("albatross"),           N_("rat"),           N_("penguin"),           N_("python"), ]# ...for a in animals:    print(_(a))

致谢

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

• Peter Funk
• James Henstridge
• JuanDavidIbáñezPalomar
• Marc-AndréLemburg
• MartinvonLüwis
• FrançoisPinard
• Barry Warsaw
• Gustavo Niemeyer

脚注