GNU gettext API?

模塊 gettext 定義了下列 API，這與 gettext API 類(lèi)似。如果你使用該 API，將會(huì )對整個(gè)應用程序產(chǎn)生全局的影響。如果你的應用程序支持多語(yǔ)種，而語(yǔ)言選擇取決于用戶(hù)的語(yǔ)言環(huán)境設置，這通常正是你所想要的。而如果你正在本地化某個(gè) Python 模塊，或者你的應用程序需要在運行時(shí)切換語(yǔ)言，相反你或許想用基于類(lèi)的API。

gettext.bindtextdomain(domain, localedir=None)?

將 domain 綁定到本地目錄 localedir。 更具體地來(lái)說(shuō)，模塊 gettext 將使用路徑 (在 Unix 系統中): localedir/language/LC_MESSAGES/domain.mo 查找二進(jìn)制 .mo 文件，此處對應地查找 language 的位置是環(huán)境變量 LANGUAGE, LC_ALL, LC_MESSAGES 和 LANG 中。

如果遺漏了 localedir 或者設置為 None，那么將返回當前 domain 所綁定的值 1

gettext.textdomain(domain=None)?

修改或查詢(xún)當前的全局域。如果 domain 為 None，則返回當前的全局域，不為 None 則將全局域設置為 domain，并返回它。

gettext.gettext(message)?

返回 message 的本地化翻譯，依據包括當前的全局域、語(yǔ)言和語(yǔ)言環(huán)境目錄。本函數在本地命名空間中通常有別名 _() （參考下面的示例）。

gettext.dgettext(domain, message)?

與 gettext() 類(lèi)似，但在指定的 domain 中查找 message。

gettext.ngettext(singular, plural, n)?

與 gettext() 類(lèi)似，但考慮了復數形式。如果找到了翻譯，則將 n 代入復數公式，然后返回得出的消息（某些語(yǔ)言具有兩種以上的復數形式）。如果未找到翻譯，則 n 為 1 時(shí)返回 singular，為其他數時(shí)返回 plural。

復數公式取自編目頭文件。它是 C 或 Python 表達式，有一個(gè)自變量 n，該表達式計算的是所需復數形式在編目中的索引號。關(guān)于在 .po 文件中使用的確切語(yǔ)法和各種語(yǔ)言的公式，請參閱 GNU gettext 文檔 。

gettext.dngettext(domain, singular, plural, n)?

與 ngettext() 類(lèi)似，但在指定的 domain 中查找 message。

gettext.pgettext(context, message)?

gettext.dpgettext(domain, context, message)?

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

gettext.dnpgettext(domain, context, singular, plural, n)?

與前綴中沒(méi)有 p 的相應函數類(lèi)似（即 gettext(), dgettext(), ngettext(), dngettext() ），但是僅翻譯給定的 message context。

3.8 新版功能.

注意，GNU gettext 還定義了 dcgettext() 方法，但它被認為不實(shí)用，因此目前沒(méi)有實(shí)現它。

這是該 API 的典型用法示例:

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

基于類(lèi)的 API?

與 GNU gettext API 相比，gettext 模塊的基于類(lèi)的 API 提供了更多的靈活性和更強的便利性。這是本地化 Python 應用程序和模塊的推薦方法。gettext 定義了一個(gè) GNUTranslations 類(lèi)，該類(lèi)實(shí)現了 GNU .mo 格式文件的解析，并且具有用于返回字符串的方法。本類(lèi)的實(shí)例也可以將自身作為函數 _() 安裝到內建命名空間中。

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

本函數實(shí)現了標準的 .mo 文件搜索算法。它接受一個(gè) domain，它與 textdomain() 接受的域相同?？蛇x參數 localedir 與 bindtextdomain() 中的相同?？蛇x參數 languages 是多條字符串的列表，其中每條字符串都是一種語(yǔ)言代碼。

如果沒(méi)有傳入 localedir，則使用默認的系統語(yǔ)言環(huán)境目錄。 2 如果沒(méi)有傳入 languages，則搜索以下環(huán)境變量：LANGUAGE、LC_ALL、LC_MESSAGES 和 LANG。從這些變量返回的第一個(gè)非空值將用作 languages 變量。環(huán)境變量應包含一個(gè)語(yǔ)言列表，由冒號分隔，該列表會(huì )被按冒號拆分，以產(chǎn)生所需的語(yǔ)言代碼字符串列表。

find() 將擴展并規范化 language，然后遍歷它們，搜索由這些組件構建的現有文件:

localedir/language/LC_MESSAGES/domain.mo

find() 返回找到類(lèi)似的第一個(gè)文件名。如果找不到這樣的文件，則返回 None。如果傳入了 all，它將返回一個(gè)列表，包含所有文件名，并按它們在語(yǔ)言列表或環(huán)境變量中出現的順序排列。

gettext.translation(domain, localedir=None, languages=None, class_=None, fallback=False)?

根據 domain、localedir 和 languages，返回 *Translations 實(shí)例，首先應將前述參數傳入 find() 以獲取關(guān)聯(lián)的 .mo 文件路徑的列表。名字與 .mo 文件名相同的實(shí)例將被緩存。如果傳入 class_，它將是實(shí)際被實(shí)例化的類(lèi)，否則實(shí)例化 GNUTranslations。類(lèi)的構造函數必須只接受一個(gè) 文件對象 參數。如果傳入 codeset，那么在 lgettext() 和 lngettext() 方法中，對翻譯后的字符串進(jìn)行編碼的字符集將被改變。

如果找到多個(gè)文件，后找到的文件將用作先前文件的替補。為了設置替補，將使用 copy.copy() 從緩存中克隆每個(gè) translation 對象。實(shí)際的實(shí)例數據仍在緩存中共享。

如果 .mo 文件未找到，且 fallback 為 false（默認值），則本函數引發(fā) OSError 異常，如果 fallback 為 true，則返回一個(gè) NullTranslations 實(shí)例。

在 3.3 版更改: 曾經(jīng)是 IOError 被引發(fā)而不是 OSError 。

在 3.11 版更改: codeset parameter is removed.

gettext.install(domain, localedir=None, *, names=None)?

This installs the function _() in Python's builtins namespace, based on domain and localedir which are passed to the function translation().

names 參數的信息請參閱 translation 對象的 install() 方法的描述。

如下所示，通常將字符串包括在 _() 函數的調用中，以標記應用程序中待翻譯的字符串，就像這樣:

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

為了方便，一般將 _() 函數安裝在 Python 內建命名空間中，以便在應用程序的所有模塊中輕松訪(fǎng)問(wèn)它。

在 3.11 版更改: names is now a keyword-only parameter.

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

國際化 (I18N) 你的程序和模塊?

國際化 (I18N) 是指使程序可切換多種語(yǔ)言的操作。本地化 (L10N) 是指程序的適配能力，一旦程序被國際化，就能適配當地的語(yǔ)言和文化習慣。為了向 Python 程序提供不同語(yǔ)言的消息，需要執行以下步驟：

1. 準備程序或模塊，將可翻譯的字符串特別標記起來(lái)

2. 在已標記的文件上運行一套工具，用來(lái)生成原始消息編目

3. 創(chuàng )建消息編目的不同語(yǔ)言的翻譯

4. 使用 gettext 模塊，以便正確翻譯消息字符串

為了準備代碼以達成 I18N，需要巡視文件中的所有字符串。所有要翻譯的字符串都應包括在 _('...') 內，以此打上標記——也就是調用 _() 函數。例如:

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

在這個(gè)例子中，字符串 'writing a log message' 被標記為待翻譯，而字符串 'mylog.txt' 和 'w' 沒(méi)有被標記。

有一些工具可以將待翻譯的字符串提取出來(lái)。原版的 GNU gettext 僅支持 C 或 C++ 源代碼，但其擴展版 xgettext 可以?huà)呙瓒喾N語(yǔ)言的代碼（包括 Python），來(lái)找出標記為可翻譯的字符串。Babel 是一個(gè) Python 國際化庫，其中包含一個(gè) pybabel 腳本，用于提取并編譯消息編目。Fran?ois Pinard 寫(xiě)的稱(chēng)為 xpot 的程序也能完成類(lèi)似的工作，可從他的 po-utils 軟件包 中獲取。

（Python 還包括了這些程序的純 Python 版本，稱(chēng)為 pygettext.py 和 msgfmt.py，某些 Python 發(fā)行版已經(jīng)安裝了它們。pygettext.py 類(lèi)似于 xgettext，但只能理解 Python 源代碼，無(wú)法處理諸如 C 或 C++ 的其他編程語(yǔ)言。pygettext.py 支持的命令行界面類(lèi)似于 xgettext，查看其詳細用法請運行 pygettext.py --help。msgfmt.py 與 GNU msgfmt 是二進(jìn)制兼容的。有了這兩個(gè)程序，可以不需要 GNU gettext 包來(lái)國際化 Python 應用程序。）

xgettext、pygettext 或類(lèi)似工具生成的 .po 文件就是消息編目。它們是結構化的人類(lèi)可讀文件，包含源代碼中所有被標記的字符串，以及這些字符串的翻譯的占位符。

然后把這些 .po 文件的副本交給各個(gè)人工譯者，他們?yōu)樗С值拿糠N自然語(yǔ)言編寫(xiě)翻譯。譯者以 <語(yǔ)言名稱(chēng)>.po 文件的形式發(fā)送回翻譯完的某個(gè)語(yǔ)言的版本，將該文件用 msgfmt 程序編譯為機器可讀的 .mo 二進(jìn)制編目文件。gettext 模塊使用 .mo 文件在運行時(shí)進(jìn)行實(shí)際的翻譯處理。

如何在代碼中使用 gettext 模塊取決于國際化單個(gè)模塊還是整個(gè)應用程序。接下來(lái)的兩節將討論每種情況。

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'])

# 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()

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))

致謝?

以下人員為創(chuàng )建此模塊貢獻了代碼、反饋、設計建議、早期實(shí)現和寶貴的經(jīng)驗：

• Peter Funk

• James Henstridge

• Juan David Ibá?ez Palomar

• Marc-André Lemburg

• Martin von L?wis

• Fran?ois Pinard

• Barry Warsaw

• Gustavo Niemeyer

備注

1

不同系統的默認語(yǔ)言環(huán)境目錄是不同的；比如在 RedHat Linux 上是 /usr/share/locale，在 Solaris 上是 /usr/lib/locale。gettext 模塊不會(huì )支持這些基于不同系統的默認值；而它的默認值為 sys.base_prefix/share/locale （請參閱 sys.base_prefix）?；谏鲜鲈?，最好每次都在應用程序的開(kāi)頭使用明確的絕對路徑來(lái)調用 bindtextdomain()。

2

參閱上方 bindtextdomain() 的腳注。