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 variablesLANGUAGE
,LC_ALL
,LC_MESSAGES
, andLANG
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.
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 whattextdomain()
takes. Optional localedir is as inbindtextdomain()
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 tofind()
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, otherwiseGNUTranslations
. The class’s constructor must take a single file object argument. If provided, codeset will change the charset used to encode translated strings in thelgettext()
andlngettext()
methods.如果找到多个文件,后找到的文件将用作先前文件的替补。为了设置替补,将使用
copy.copy()
从缓存中克隆每个 translation 对象。实际的实例数据仍在缓存中共享。如果
.mo
文件未找到,且 fallback 为 false(默认值),则本函数引发OSError
异常,如果 fallback 为 true,则返回一个NullTranslations
实例。
-
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 classes are what actually implement the translation of original
source file message strings to translated message strings. The base class used
by all translation classes is NullTranslations
; this provides the basic
interface you can use to write your own specialized translation classes. Here
are the methods of 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)¶ If a fallback has been set, forward
gettext()
to the fallback. Otherwise, return message. Overridden in derived classes.
-
ngettext
(singular, plural, n)¶ If a fallback has been set, forward
ngettext()
to the fallback. Otherwise, return singular if n is 1; return plural otherwise. Overridden in derived classes.
-
lgettext
(message)¶
-
lngettext
(singular, plural, n)¶ Equivalent to
gettext()
andngettext()
, but the translation is returned as a byte string encoded in the preferred system encoding if no encoding was explicitly set withset_output_charset()
. Overridden in derived classes.警告
应避免在 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.
Since message ids are read as Unicode strings too, all *gettext()
methods
will assume message ids as Unicode strings, not byte strings.
The entire set of key/value pairs are placed into a dictionary and set as the
“protected” _info
instance variable.
If the .mo
file’s magic number is invalid, the major version number is
unexpected, or if other problems occur while reading the file, instantiating a
GNUTranslations
class can raise OSError
.
-
class
gettext.
GNUTranslations
¶ The following methods are overridden from the base class implementation:
-
gettext
(message)¶ Look up the message id in the catalog and return the corresponding message string, as a Unicode string. If there is no entry in the catalog for the message id, and a fallback has been set, the look up is forwarded to the fallback’s
gettext()
method. Otherwise, the message id is returned.
-
ngettext
(singular, plural, n)¶ Do a plural-forms lookup of a message id. singular is used as the message id for purposes of lookup in the catalog, while n is used to determine which plural form to use. The returned message string is a Unicode string.
If the message id is not found in the catalog, and a fallback is specified, the request is forwarded to the fallback’s
ngettext()
method. Otherwise, when n is 1 singular is returned, and plural is returned in all other cases.例如:
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)¶ Equivalent to
gettext()
andngettext()
, but the translation is returned as a byte string encoded in the preferred system encoding if no encoding was explicitly set withset_output_charset()
.警告
应避免在 Python 3 中使用这些方法。请参阅
lgettext()
函数的警告。
-
23.1.2.3. Solaris message catalog support¶
The Solaris operating system defines its own binary .mo
file format, but
since no documentation can be found on this format, it is not supported at this
time.
23.1.2.4. The Catalog constructor¶
GNOME uses a version of the gettext
module by James Henstridge, but this
version has a slightly different API. Its documented usage was:
import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))
For compatibility with this older module, the function Catalog()
is an
alias for the translation()
function described above.
One difference between this module and Henstridge’s: his catalog objects supported access through a mapping API, but this appears to be unused and so is not currently supported.
23.1.3. Internationalizing your programs and modules¶
Internationalization (I18N) refers to the operation by which a program is made aware of multiple languages. Localization (L10N) refers to the adaptation of your program, once internationalized, to the local language and cultural habits. In order to provide multilingual messages for your Python programs, you need to take the following steps:
- prepare your program or module by specially marking translatable strings
- run a suite of tools over your marked files to generate raw messages catalogs
- create language specific translations of the message catalogs
- use the
gettext
module so that message strings are properly translated
In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
it in _('...')
— that is, a call to the function _()
. For example:
filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()
In this example, the string 'writing a log message'
is marked as a candidate
for translation, while the strings 'mylog.txt'
and 'w'
are not.
There are a few tools to extract the strings meant for translation.
The original GNU gettext only supported C or C++ source
code but its extended version xgettext scans code written
in a number of languages, including Python, to find strings marked as
translatable. Babel is a Python
internationalization library that includes a pybabel
script to
extract and compile message catalogs. François Pinard’s program
called xpot does a similar job and is available as part of
his po-utils package.
(Python also includes pure-Python versions of these programs, called
pygettext.py and msgfmt.py; some Python distributions
will install them for you. pygettext.py is similar to
xgettext, but only understands Python source code and
cannot handle other programming languages such as C or C++.
pygettext.py supports a command-line interface similar to
xgettext; for details on its use, run pygettext.py
--help
. msgfmt.py is binary compatible with GNU
msgfmt. With these two programs, you may not need the GNU
gettext package to internationalize your Python
applications.)
xgettext, pygettext, and similar tools generate
.po
files that are message catalogs. They are structured
human-readable files that contain every marked string in the source
code, along with a placeholder for the translated versions of these
strings.
Copies of these .po
files are then handed over to the
individual human translators who write translations for every
supported natural language. They send back the completed
language-specific versions as a <language-name>.po
file that’s
compiled into a machine-readable .mo
binary catalog file using
the msgfmt program. The .mo
files are used by the
gettext
module for the actual translation processing at
run-time.
How you use the gettext
module in your code depends on whether you are
internationalizing a single module or your entire application. The next two
sections will discuss each case.
23.1.3.1. Localizing your module¶
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.
Let’s say your module is called “spam” and the module’s various natural language
translation .mo
files reside in /usr/share/locale
in GNU
gettext format. Here’s what you would put at the top of your
module:
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext
23.1.3.2. Localizing your application¶
If you are localizing your application, you can install the _()
function
globally into the built-in namespace, usually in the main driver file of your
application. This will let all your application-specific files just use
_('...')
without having to explicitly install it in each file.
In the simple case then, you need only add the following bit of code to the main driver file of your application:
import gettext
gettext.install('myapplication')
If you need to set the locale directory, you can pass it into the
install()
function:
import gettext
gettext.install('myapplication', '/usr/share/locale')
23.1.3.3. Changing languages on the fly¶
If your program needs to support many languages at the same time, you may want to create multiple translation instances and then switch between them explicitly, like so:
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. Deferred translations¶
In most coding situations, strings are translated where they are coded. Occasionally however, you need to mark strings for translation, but defer actual translation until later. A classic example is:
animals = ['mollusk',
'albatross',
'rat',
'penguin',
'python', ]
# ...
for a in animals:
print(a)
Here, you want to mark the strings in the animals
list as being
translatable, but you don’t actually want to translate them until they are
printed.
Here is one way you can handle this situation:
def _(message): return message
animals = [_('mollusk'),
_('albatross'),
_('rat'),
_('penguin'),
_('python'), ]
del _
# ...
for a in animals:
print(_(a))
This works because the dummy definition of _()
simply returns the string
unchanged. And this dummy definition will temporarily override any definition
of _()
in the built-in namespace (until the del
command). Take
care, though if you have a previous definition of _()
in the local
namespace.
Note that the second use of _()
will not identify “a” as being
translatable to the gettext program, because the parameter
is not a string literal.
Another way to handle this is with the following example:
def N_(message): return message
animals = [N_('mollusk'),
N_('albatross'),
N_('rat'),
N_('penguin'),
N_('python'), ]
# ...
for a in animals:
print(_(a))
In this case, you are marking translatable strings with the function
N_()
, which won’t conflict with any definition of _()
.
However, you will need to teach your message extraction program to
look for translatable strings marked with N_()
. xgettext,
pygettext, pybabel extract
, and xpot all
support this through the use of the -k
command-line switch.
The choice of N_()
here is totally arbitrary; it could have just
as easily been 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] | See the footnote for bindtextdomain() above. |