23.1. "gettext" --- 多语种国际化服务
************************************

**源代码：** Lib/gettext.py

======================================================================

The "gettext" module provides internationalization (I18N) and
localization (L10N) services for your Python modules and applications.
It supports both the GNU "gettext" message catalog API and a higher
level, class-based API that may be more appropriate for Python files.
The interface described below allows you to write your module and
application messages in one natural language, and provide a catalog of
translated messages for running under different natural languages.

同时还给出一些本地化 Python 模块及应用程序的小技巧。


23.1.1. GNU **gettext** API
===========================

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

gettext.bindtextdomain(domain, localedir=None)

   Bind the *domain* to the locale directory *localedir*.  More
   concretely, "gettext" will look for binary ".mo" files for the
   given domain using the path (on Unix):
   "localedir/language/LC_MESSAGES/domain.mo", where *languages* is
   searched for in the environment variables "LANGUAGE", "LC_ALL",
   "LC_MESSAGES", and "LANG" respectively.

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

gettext.bind_textdomain_codeset(domain, codeset=None)

   将 *domain* 绑定到 *codeset*，修改 "lgettext()", "ldgettext()",
   "lngettext()" 和 "ldngettext()" 函数返回的字节串的字符编码。如果省
   略了 *codeset*，则返回当前绑定的编码集。

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.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()" 显式设置其他编码，则返回的翻译将以首选
   系统编码来编码字节串。

   警告:

     These functions should be avoided in Python 3, because they
     return encoded bytes.  It's much better to use alternatives which
     return Unicode strings instead, since most Python applications
     will want to manipulate human readable text as strings instead of
     bytes.  Further, it's possible that you may get unexpected
     Unicode-related exceptions if there are encoding problems with
     the translated strings.  It is possible that the "l*()" functions
     will be deprecated in future Python versions due to their
     inherent problems and limitations.

注意，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.'))


23.1.2. 基于类的 API
====================

The class-based API of the "gettext" module gives you more flexibility
and greater convenience than the GNU **gettext** API.  It is the
recommended way of localizing your Python applications and modules.
"gettext" defines a "translations" class which implements the parsing
of GNU ".mo" format files, and has methods for returning strings.
Instances of this "translations" class can also install themselves in
the built-in namespace as the function "_()".

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

   This function implements the standard ".mo" file search algorithm.
   It takes a *domain*, identical to what "textdomain()" takes.
   Optional *localedir* is as in "bindtextdomain()"  Optional
   *languages* is a list of strings, where each string is a language
   code.

   如果没有传入 *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, codeset=None)

   Return a "Translations" instance based on the *domain*,
   *localedir*, and *languages*, which are first passed to "find()" to
   get a list of the associated ".mo" file paths.  Instances with
   identical ".mo" file names are cached.  The actual class
   instantiated is either *class_* if provided, otherwise
   "GNUTranslations".  The class's constructor must take a single
   *file object* argument.  If provided, *codeset* will change the
   charset used to encode translated strings in the "lgettext()" and
   "lngettext()" methods.

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

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

   3.3 版更變: "IOError" 代替 "OSError" 被引发。

gettext.install(domain, localedir=None, codeset=None, names=None)

   根据传入 "translation()" 函数的 *domain*、*localedir* 和 *codeset*
   ，在 Python 内建命名空间中安装 "_()" 函数。

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

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

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

   为了方便，一般将 "_()" 函数安装在 Python 内建命名空间中，以便在应用
   程序的所有模块中轻松访问它。


23.1.2.1. "NullTranslations" 类
-------------------------------

translation 类实际实现的是，将原始源文件消息字符串转换为已翻译的消息字
符串。所有 translation 类使用的基类为 "NullTranslations"，它提供了基本
的接口，可用于编写自己定制的 translation 类。以下是 "NullTranslations"
的方法：

class gettext.NullTranslations(fp=None)

   接受一个可选参数 *文件对象* *fp*，该参数会被基类忽略。初始化由派生
   类设置的 "protected" （受保护的）实例变量 *_info* 和 *_charset*，与
   *_fallback* 类似，但它是通过 "add_fallback()" 来设置的。如果 *fp*
   不为 "None"，就会调用 "self._parse(fp)"。

   _parse(fp)

      No-op'd in the base class, this method takes file object *fp*,
      and reads the data from the file, initializing its message
      catalog.  If you have an unsupported message catalog file
      format, you should override this method to parse your format.

   add_fallback(fallback)

      添加 *fallback* 为当前 translation 对象的替补对象。如果
      translation 对象无法为指定消息提供翻译，则应向替补查询。

   gettext(message)

      如果设置了替补，则转发 "gettext()" 给替补。否则返回 *message*。
      须在派生类中重写。

   ngettext(singular, plural, n)

      如果设置了替补，则转发 "ngettext()" 给替补。否则，*n* 为 1 时返
      回 *singular*，为其他时返回 *plural*。须在派生类中重写。

   lgettext(message)

   lngettext(singular, plural, n)

      与 "gettext()" 和 "ngettext()" 等效，但是如果没有用
      "set_output_charset()" 显式设置编码，则返回的翻译将以首选系统编
      码来编码字节串。在派生类中被重写。

      警告:

        应避免在 Python 3 中使用这些方法。请参阅 "lgettext()" 函数的警
        告。

   info()

      Return the "protected" "_info" variable.

   charset()

      返回消息编目文件的编码。

   output_charset()

      返回由 "lgettext()" 和 "lngettext()" 翻译的消息的编码。

   set_output_charset(charset)

      更改翻译出的消息的编码。

   install(names=None)

      本方法将 "gettext()" 安装至内建命名空间，并绑定为 "_"。

      If the *names* parameter is given, it must be a sequence
      containing the names of functions you want to install in the
      builtins namespace in addition to "_()".  Supported names are
      "'gettext'", "'ngettext'", "'lgettext'" and "'lngettext'".

      注意，这仅仅是使 "_()" 函数在应用程序中生效的一种方法，尽管也是
      最方便的方法。由于它会影响整个应用程序全局，特别是内建命名空间，
      因此已经本地化的模块不应该安装 "_()"，而是应该用下列代码使 "_()"
      在各自模块中生效:

         import gettext
         t = gettext.translation('mymodule', ...)
         _ = t.gettext

      这只将 "_()" 放在其模块的全局命名空间中，所以只影响其模块内的调
      用。


23.1.2.2. "GNUTranslations" 类
------------------------------

"gettext" 模块提供了一个派生自 "NullTranslations" 的其他类：
"GNUTranslations"。该类重写了 "_parse()"，同时能以大端序和小端序格式读
取 GNU **gettext** 格式的 ".mo" 文件。

"GNUTranslations" parses optional meta-data out of the translation
catalog.  It is convention with GNU **gettext** to include meta-data
as the translation for the empty string.  This meta-data is in **RFC
822**-style "key: value" pairs, and should contain the "Project-Id-
Version" key.  If the key "Content-Type" is found, then the "charset"
property is used to initialize the "protected" "_charset" instance
variable, defaulting to "None" if not found.  If the charset encoding
is specified, then all message ids and message strings read from the
catalog are converted to Unicode using this encoding, else ASCII
encoding is assumed.

由于消息 ID 也是作为 Unicode 字符串读取的，因此所有 "*gettext()" 方法
都假定消息 ID 为 Unicode 字符串，而不是字节串。

整个键/值对集合将被放入一个字典，并设置为 "protected"（受保护的）
"_info" 实例变量。

如果 ".mo" 文件的魔法值 (magic number) 无效，或遇到意外的主版本号，或
在读取文件时发生其他问题，则实例化 "GNUTranslations" 类会引发
"OSError"。

class gettext.GNUTranslations

   下列方法是根据基类实现重写的：

   gettext(message)

      在编目中查找 *message* ID，并以 Unicode 字符串形式返回相应的消息
      字符串。如果在编目中没有 *message* ID 条目，且配置了替补，则查找
      请求将被转发到替补的 "gettext()" 方法。否则，返回 *message* ID。

   ngettext(singular, plural, n)

      查找消息 ID 的复数形式。*singular* 用作消息 ID，用于在编目中查找
      ，同时 *n* 用于确定使用哪种复数形式。返回的消息字符串是 Unicode
      字符串。

      如果在编目中没有找到消息 ID，且配置了替补，则查找请求将被转发到
      替补的 "ngettext()" 方法。否则，当 *n* 为 1 时返回 *singular*，
      其他情况返回 *plural*。

      例如：

         n = len(os.listdir('.'))
         cat = GNUTranslations(somefile)
         message = cat.ngettext(
             'There is %(num)d file in this directory',
             'There are %(num)d files in this directory',
             n) % {'num': n}

   lgettext(message)

   lngettext(singular, plural, n)

      与 "gettext()" 和 "ngettext()" 等效，但是如果没有用
      "set_output_charset()" 显式设置编码，则返回的翻译将以首选系统编
      码来编码字节串。

      警告:

        应避免在 Python 3 中使用这些方法。请参阅 "lgettext()" 函数的警
        告。


23.1.2.3. Solaris 消息编目支持
------------------------------

Solaris 操作系统定义了自己的二进制 ".mo" 文件格式，但由于找不到该格式
的文档，因此目前不支持该格式。


23.1.2.4. 编目构造器
--------------------

GNOME 用的 "gettext" 模块是 James Henstridge 写的版本，但该版本的 API
略有不同。它文档中的用法是:

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

为了与本模块的旧版本兼容，"Catalog()" 函数是上述 "translation()" 函数
的别名。

本模块与 Henstridge 的模块有一个区别：他的编目对象支持通过映射 API 进
行访问，但是该特性似乎从未使用过，因此目前不支持该特性。


23.1.3. 国际化 (I18N) 你的程序和模块
====================================

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

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

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

3. create language specific translations of the message catalogs

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 是一个 Python 国际化库，其
中包含一个 "pybabel" 脚本，用于提取并编译消息编目。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" 模块取决于国际化单个模块还是整个应用程序。
接下来的两节将讨论每种情况。


23.1.3.1. 本地化你的模块
------------------------

If you are localizing your module, you must take care not to make
global changes, e.g. to the built-in namespace.  You should not use
the GNU "gettext" API but instead the class-based API.

假设你的模块叫做 "spam"，并且该模块的各种自然语言翻译 ".mo" 文件存放于
"/usr/share/locale"，为 GNU **gettext** 格式。以下内容应放在模块顶部:

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


23.1.3.2. 本地化你的应用程序
----------------------------

如果正在本地化应用程序，可以将 "_()" 函数全局安装到内建命名空间中，通
常在应用程序的主文件中安装。这将使某个应用程序的所有文件都能使用
"_('...')"，而不必在每个文件中显式安装它。

最简单的情况，就只需将以下代码添加到应用程序的主程序文件中:

   import gettext
   gettext.install('myapplication')

如果需要设置语言环境目录，可以将其传递给 "install()" 函数:

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


23.1.3.3. 即时更改语言
----------------------

如果程序需要同时支持多种语言，则可能需要创建多个翻译实例，然后在它们之
间进行显式切换，如下所示:

   import gettext

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

   # start by using language1
   lang1.install()

   # ... time goes by, user selects language 2
   lang2.install()

   # ... more time goes by, user selects language 3
   lang3.install()


23.1.3.4. 延迟翻译
------------------

在大多数代码中，字符串会在编写位置进行翻译。但偶尔需要将字符串标记为待
翻译，实际翻译却推迟到后面。一个典型的例子是:

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

此处希望将 "animals" 列表中的字符串标记为可翻译，但不希望在打印之前对
它们进行翻译。

这是处理该情况的一种方式:

   def _(message): return message

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

   del _

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

该方法之所以可行，是因为 "_()" 的虚定义只是简单地返回了原本的字符串。
并且该虚定义将临时覆盖内建命名空间中 "_()" 的定义（直到 "del" 命令）。
即使先前在本地命名空间中已经有了 "_()" 的定义也请注意。

注意，第二次使用 "_()" 不会认为 "a" 可以传递给 **gettext** 程序去翻译
，因为该参数不是字符串文字。

解决该问题的另一种方法是下面这个例子:

   def N_(message): return message

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

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

这种情况下标记可翻译的字符串使用的是函数 "N_()"，该函数不会与 "_()" 的
任何定义冲突。但是，需要教会消息提取程序去寻找用 "N_()" 标记的可翻译字
符串。**xgettext**, **pygettext**, "pybabel extract" 和 **xpot** 都支
持此功能，使用 "-k" 命令行开关即可。这里选择 "N_()" 为名称完全是任意的
，它也能轻易改为 "MarkThisStringForTranslation()"。


23.1.4. 致谢
============

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

* Peter Funk

* James Henstridge

* Juan David Ibáñez Palomar

* Marc-André Lemburg

* Martin von Löwis

* François Pinard

* Barry Warsaw

* Gustavo Niemeyer

-[ 註解 ]-

[1] The default locale directory is system dependent; for example, on
    RedHat Linux it is "/usr/share/locale", but on Solaris it is
    "/usr/lib/locale". The "gettext" module does not try to support
    these system dependent defaults; instead its default is
    "sys.prefix/share/locale". For this reason, it is always best to
    call "bindtextdomain()" with an explicit absolute path at the
    start of your application.

[2] 参阅上方 "bindtextdomain()" 的脚注。
