`locale` — 國際化服務¶

locale 模組提供對 POSIX 區域設定資料庫和功能的訪問。 POSIX 區域設定機制允許程式設計師在應用程式中處理某些文化問題，而無需程式設計師瞭解軟體執行的每個國家/地區的具體細節。

locale 模組是在 _locale 模組之上實現的，而 _locale 模組在可用時使用 ANSI C 區域設定實現。

locale 模組定義了以下異常和函式

exception locale.Error¶: 當傳遞給 setlocale() 的區域設定無法識別時引發的異常。

locale.setlocale(category, locale=None)¶

如果給定了 locale 且不為 None，則 setlocale() 會修改 category 的區域設定。可用類別在下面的資料描述中列出。locale 可以是字串，也可以是兩個字串（語言程式碼和編碼）的可迭代物件。如果它是可迭代的，它會使用區域設定別名引擎轉換為區域設定名稱。空字串指定使用者的預設設定。如果區域設定的修改失敗，則會引發 Error 異常。如果成功，則返回新的區域設定。

如果省略了 locale 或為 None，則返回 category 的當前設定。

在大多數系統上，setlocale() 不是執行緒安全的。應用程式通常以呼叫開始

import locale
locale.setlocale(locale.LC_ALL, '')

這將所有類別的區域設定設定為使用者的預設設定（通常在 LANG 環境變數中指定）。如果此後未更改區域設定，則使用多執行緒不應引起問題。

locale.localeconv()¶

以字典形式返回本地約定的資料庫。此字典具有以下字串作為鍵

類別	鍵	含義
`LC_NUMERIC`	`'decimal_point'`	小數點字元。
	`'grouping'`	指定期望 `'thousands_sep'` 的相對位置的數字序列。如果序列以 `CHAR_MAX` 終止，則不執行進一步的分組。如果序列以 `0` 終止，則重複使用最後一個組大小。
	`'thousands_sep'`	組之間使用的字元。
`LC_MONETARY`	`'int_curr_symbol'`	國際貨幣符號。
	`'currency_symbol'`	本地貨幣符號。
	`'p_cs_precedes/n_cs_precedes'`	貨幣符號是否位於值之前（對於正值和負值）。
	`'p_sep_by_space/n_sep_by_space'`	貨幣符號是否與值之間用空格隔開（對於正值和負值）。
	`'mon_decimal_point'`	用於貨幣值的小數點。
	`'frac_digits'`	在本地格式化貨幣值時使用的小數位數。
	`'int_frac_digits'`	在國際格式化貨幣值時使用的小數位數。
	`'mon_thousands_sep'`	用於貨幣值的分組分隔符。
	`'mon_grouping'`	與 `'grouping'` 等效，用於貨幣值。
	`'positive_sign'`	用於註釋正貨幣值的符號。
	`'negative_sign'`	用於註釋負貨幣值的符號。
	`'p_sign_posn/n_sign_posn'`	符號的位置（對於正值和負值），請參見下文。

所有數值都可以設定為 CHAR_MAX，以指示此區域設定中未指定任何值。

'p_sign_posn' 和 'n_sign_posn' 的可能值如下所示。

值	說明
`0`	貨幣和值用括號括起來。
`1`	符號應位於值和貨幣符號之前。
`2`	符號應位於值和貨幣符號之後。
`3`	符號應緊跟在值之前。
`4`	符號應緊跟在值之後。
`CHAR_MAX`	此區域設定中未指定任何內容。

如果區域設定不同且數字或貨幣字串為非 ASCII，則該函式會將 LC_CTYPE 區域設定臨時設定為 LC_NUMERIC 區域設定或 LC_MONETARY 區域設定。此臨時更改會影響其他執行緒。

在 3.7 版本中更改: 該函式現在會在某些情況下將 LC_CTYPE 區域設定臨時設定為 LC_NUMERIC 區域設定。

locale.nl_langinfo(option)¶

以字串形式返回某些特定於區域設定的資訊。此函式並非在所有系統上都可用，並且可能選項集也可能因平臺而異。可能的引數值是數字，可以使用 locale 模組中的符號常量。

nl_langinfo() 函式接受以下鍵之一。大多數描述取自 GNU C 庫中的相應描述。

locale.CODESET¶: 獲取一個字串，其中包含所選區域設定中使用的字元編碼的名稱。

locale.D_T_FMT¶: 獲取一個可以用作 time.strftime() 的格式字串的字串，以特定於區域設定的方式表示日期和時間。

locale.D_FMT¶: 獲取一個可以用作 time.strftime() 的格式字串的字串，以特定於區域設定的方式表示日期。

locale.T_FMT¶: 獲取一個可以用作 time.strftime() 的格式字串的字串，以特定於區域設定的方式表示時間。

locale.T_FMT_AMPM¶: 獲取 time.strftime() 的格式字串，以 am/pm 格式表示時間。

locale.DAY_1¶
locale.DAY_2¶
locale.DAY_3¶
locale.DAY_4¶
locale.DAY_5¶
locale.DAY_6¶
locale.DAY_7¶: 獲取星期中第 n 天的名稱。

注意

這遵循美國的慣例，即 DAY_1 為星期日，而不是國際慣例（ISO 8601）中星期一為一週的第一天。

locale.ABDAY_1¶
locale.ABDAY_2¶
locale.ABDAY_3¶
locale.ABDAY_4¶
locale.ABDAY_5¶
locale.ABDAY_6¶
locale.ABDAY_7¶: 獲取星期中第 n 天的縮寫名稱。

locale.MON_1¶
locale.MON_2¶
locale.MON_3¶
locale.MON_4¶
locale.MON_5¶
locale.MON_6¶
locale.MON_7¶
locale.MON_8¶
locale.MON_9¶
locale.MON_10¶
locale.MON_11¶
locale.MON_12¶: 獲取第 n 個月份的名稱。

locale.ABMON_1¶
locale.ABMON_2¶
locale.ABMON_3¶
locale.ABMON_4¶
locale.ABMON_5¶
locale.ABMON_6¶
locale.ABMON_7¶
locale.ABMON_8¶
locale.ABMON_9¶
locale.ABMON_10¶
locale.ABMON_11¶
locale.ABMON_12¶: 獲取第 n 個月份的縮寫名稱。

locale.RADIXCHAR¶: 獲取基數字符（小數點、小數逗號等）。

locale.THOUSEP¶: 獲取千位分隔符（三位數字一組）。

locale.YESEXPR¶: 獲取一個正則表示式，該表示式可以與 regex 函式一起使用，以識別對“是/否”問題的肯定答覆。

locale.NOEXPR¶: 獲取一個正則表示式，該表示式可以與 regex(3) 函式一起使用，以識別對“是/否”問題的否定答覆。

注意

YESEXPR 和 NOEXPR 的正則表示式使用適用於 C 庫中 regex 函式的語法，該語法可能與 re 中使用的語法不同。

locale.CRNCYSTR¶: 獲取貨幣符號，如果該符號應顯示在值之前，則以“-”開頭；如果該符號應顯示在值之後，則以“+”開頭；如果該符號應替換基數字符，則以“.”開頭。

locale.ERA¶

獲取一個字串，該字串描述如何在區域設定中為每個紀元計數和顯示年份。

大多數區域設定沒有定義此值。一個定義此值的區域設定示例是日語區域設定。在日本，傳統的日期表示形式包括與當時天皇統治相對應的紀元名稱。

通常，沒有必要直接使用此值。在它們的格式字串中指定 E 修飾符會導致 time.strftime() 函式使用此資訊。返回字串的格式在The Open Group Base Specifications Issue 8 的 7.3.5.2 LC_TIME C-Language Access 段落中指定。

locale.ERA_D_T_FMT¶: 獲取 time.strftime() 的格式字串，以特定於區域設定的基於紀元的方式表示日期和時間。

locale.ERA_D_FMT¶: 獲取 time.strftime() 的格式字串，以特定於區域設定的基於紀元的方式表示日期。

locale.ERA_T_FMT¶: 獲取 time.strftime() 的格式字串，以特定於區域設定的基於紀元的方式表示時間。

locale.ALT_DIGITS¶: 獲取一個字串，該字串由最多 100 個以分號分隔的符號組成，用於以特定於區域設定的方式表示值 0 到 99。在大多數區域設定中，這是一個空字串。

locale.getdefaultlocale([envvars])¶

嘗試確定預設的區域設定並將其作為 (語言程式碼, 編碼) 形式的元組返回。

根據 POSIX，一個沒有呼叫 setlocale(LC_ALL, '') 的程式使用可移植的 'C' 區域設定執行。呼叫 setlocale(LC_ALL, '') 可以讓它使用由 LANG 變數定義的預設區域設定。由於我們不想幹擾當前的區域設定，因此我們以上述方式模擬該行為。

為了保持與其他平臺的相容性，不僅會測試 LANG 變數，還會測試作為 envvars 引數給出的變數列表。將使用找到的第一個已定義的變數。envvars 預設為 GNU gettext 中使用的搜尋路徑；它必須始終包含變數名 'LANG'。GNU gettext 搜尋路徑按順序包含 'LC_ALL'、'LC_CTYPE'、'LANG' 和 'LANGUAGE'。

除了程式碼 'C' 之外，語言程式碼對應於 RFC 1766。如果無法確定 語言程式碼 和編碼的值，則它們可能為 None。

自 3.11 版本起已棄用，將在 3.15 版本中刪除。

locale.getlocale(category=LC_CTYPE)¶

返回給定區域設定類別的當前設定，以包含 語言程式碼、編碼的序列形式。category 可以是 LC_* 值之一，但 LC_ALL 除外。預設為 LC_CTYPE。

除了程式碼 'C' 之外，語言程式碼對應於 RFC 1766。如果無法確定 語言程式碼 和編碼的值，則它們可能為 None。

locale.getpreferredencoding(do_setlocale=True)¶

根據使用者偏好，返回用於文字資料的區域設定編碼。使用者偏好在不同的系統上以不同的方式表達，並且在某些系統上可能無法以程式設計方式獲得，因此此函式僅返回一個猜測值。

在某些系統上，有必要呼叫 setlocale() 以獲取使用者偏好，因此此函式不是執行緒安全的。如果不需要或不希望呼叫 setlocale，則應將 do_setlocale 設定為 False。

在 Android 上或如果啟用了Python UTF-8 模式，始終返回 'utf-8'，區域設定編碼和 do_setlocale 引數將被忽略。

Python 預初始化配置 LC_CTYPE 區域設定。另請參閱檔案系統編碼和錯誤處理程式。

在 3.7 版本中更改: 該函式現在在 Android 上或如果啟用了Python UTF-8 模式，始終返回 "utf-8"。

locale.getencoding()¶

獲取當前的區域設定編碼

在 Android 和 VxWorks 上，返回 "utf-8"。
在 Unix 上，返回當前 LC_CTYPE 區域設定的編碼。如果 nl_langinfo(CODESET) 返回空字串，則返回 "utf-8"：例如，如果當前 LC_CTYPE 區域設定不受支援。
在 Windows 上，返回 ANSI 內碼表。

Python 預初始化配置 LC_CTYPE 區域設定。另請參閱檔案系統編碼和錯誤處理程式。

此函式類似於 getpreferredencoding(False)，只是此函式忽略了Python UTF-8 模式。

在 3.11 版本中新增。

locale.normalize(localename)¶

返回給定區域設定名稱的規範化區域設定程式碼。返回的區域設定程式碼的格式用於 setlocale()。如果規範化失敗，則返回原始名稱，不做更改。

如果給定的編碼未知，則該函式將像 setlocale() 一樣，預設為區域設定程式碼的預設編碼。

locale.strcoll(string1, string2)¶: 根據當前的 LC_COLLATE 設定比較兩個字串。與其他任何比較函式一樣，根據 string1 是否在 string2 之前或之後排序，或者是否等於 string2，返回負值、正值或 0。

locale.strxfrm(string)¶: 將字串轉換為可在區域設定感知比較中使用的字串。例如，strxfrm(s1) < strxfrm(s2) 等效於 strcoll(s1, s2) < 0。當重複比較相同的字串時，可以使用此函式，例如，在排序字串序列時。

locale.format_string(format, val, grouping=False, monetary=False)¶

根據當前的 LC_NUMERIC 設定格式化數字 val 。該格式遵循 % 運算子的約定。對於浮點值，如果合適，則會修改小數點。如果 grouping 為 True，則還會考慮分組。

如果 monetary 為 true，則轉換將使用貨幣千位分隔符和分組字串。

處理格式說明符，如 format % val，但會考慮當前的區域設定。

在 3.7 版本中更改: 添加了 monetary 關鍵字引數。

locale.currency(val, symbol=True, grouping=False, international=False)¶

根據當前的 LC_MONETARY 設定格式化數字 val 。

如果 symbol 為 true（預設情況），則返回的字串包含貨幣符號。如果 grouping 為 True（非預設情況），則會使用值進行分組。如果 international 為 True（非預設情況），則使用國際貨幣符號。

注意

此函式不適用於“C”區域設定，因此您必須首先透過 setlocale() 設定區域設定。

locale.str(float)¶: 使用與內建函式 str(float) 相同的格式格式化浮點數，但會考慮小數點。

locale.delocalize(string)¶: 根據 LC_NUMERIC 設定，將字串轉換為規範化的數字字串。

在 3.5 版本中新增。

locale.localize(string, grouping=False, monetary=False)¶: 根據 LC_NUMERIC 設定，將規範化的數字字串轉換為格式化的字串。

在 3.10 版本中新增。

locale.atof(string, func=float)¶: 透過對 string 呼叫 delocalize() 的結果呼叫 func ，根據 LC_NUMERIC 設定將字串轉換為數字。

locale.atoi(string)¶: 根據 LC_NUMERIC 約定，將字串轉換為整數。

locale.LC_CTYPE¶

字元型別函式的區域設定類別。最重要的是，此類別定義了文字編碼，即如何將位元組解釋為 Unicode 程式碼點。有關如何將此變數自動強制轉換為 C.UTF-8 以避免容器中無效設定或透過遠端 SSH 連線傳遞的不相容設定引起的問題，請參閱 PEP 538 和 PEP 540。

Python 內部不使用來自 ctype.h 的依賴於區域設定的字元轉換函式。相反，內部 pyctype.h 提供了與區域設定無關的等效項，例如 Py_TOLOWER。

locale.LC_COLLATE¶: 用於排序字串的區域設定類別。 strcoll() 和 strxfrm() 函式受到 locale 模組的影響。

locale.LC_TIME¶: 用於格式化時間的區域設定類別。 time.strftime() 函式遵循這些約定。

locale.LC_MONETARY¶: 用於格式化貨幣值的區域設定類別。可用選項可透過 localeconv() 函式獲得。

locale.LC_MESSAGES¶

用於訊息顯示的區域設定類別。 Python 目前不支援特定於應用程式的、感知區域設定的訊息。作業系統顯示的訊息，例如 os.strerror() 返回的訊息，可能會受此類別的影響。

此值可能在不符合 POSIX 標準的作業系統（尤其是 Windows）上不可用。

locale.LC_NUMERIC¶: 用於格式化數字的區域設定類別。 format_string()、 atoi()、 atof() 和 str() 函式受到 locale 模組的該類別影響。所有其他數字格式化操作不受影響。

locale.LC_ALL¶: 所有區域設定的組合。如果在更改區域設定時使用此標誌，則會嘗試設定所有類別的區域設定。如果任何類別失敗，則不會更改任何類別。使用此標誌檢索區域設定時，將返回一個指示所有類別設定的字串。此字串稍後可用於恢復設定。

locale.CHAR_MAX¶: 這是一個符號常量，用於 localeconv() 返回的不同值。

示例

>>> import locale
>>> loc = locale.getlocale()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale

背景、詳細資訊、提示和注意事項¶

C 標準將區域設定定義為程式範圍的屬性，更改此屬性的開銷可能相對較高。最重要的是，某些實現存在缺陷，頻繁更改區域設定可能會導致核心轉儲。這使得正確使用區域設定有些麻煩。

最初，當程式啟動時，區域設定是 C 區域設定，無論使用者的首選區域設定是什麼。有一個例外：LC_CTYPE 類別在啟動時更改，以將當前區域設定編碼設定為使用者的首選區域設定編碼。程式必須透過呼叫 setlocale(LC_ALL, '') 明確表示需要使用者其他類別的首選區域設定。

在某些庫例程中呼叫 setlocale() 通常不是一個好主意，因為它會影響整個程式。儲存和恢復它幾乎一樣糟糕：它開銷很大，並且會影響在設定恢復之前恰好執行的其他執行緒。

如果，在編寫通用模組時，你需要一個不受區域設定影響的操作版本（例如，與 time.strftime() 一起使用的某些格式），你需要找到一種不使用標準庫例程的方法來實現它。更好的方法是說服自己使用區域設定是可以的。只有在迫不得已的情況下，才應該記錄你的模組與非 C 區域設定不相容。

根據區域設定執行數值運算的唯一方法是使用此模組定義的特殊函式：atof()、atoi()、format_string()、str()。

沒有辦法根據區域設定執行大小寫轉換和字元分類。對於（Unicode）文字字串，這些操作僅根據字元值執行，而對於位元組字串，轉換和分類則根據位元組的 ASCII 值執行，並且高位已設定的位元組（即，非 ASCII 位元組）永遠不會被轉換或被認為是字母或空格等字元類的一部分。

對於擴充套件編寫者和嵌入 Python 的程式¶

擴充套件模組永遠不應呼叫 setlocale()，除非是為了找出當前的區域設定。但是，由於返回值只能以可移植的方式用於恢復它，因此這並不是很有用（除非可能是為了找出區域設定是否為 C）。

當 Python 程式碼使用 locale 模組更改區域設定時，這也會影響嵌入式應用程式。如果嵌入式應用程式不希望發生這種情況，則應從 config.c 檔案中內建模組的表中刪除 _locale 擴充套件模組（它完成所有工作），並確保 _locale 模組不能作為共享庫訪問。

訪問訊息目錄¶

locale.gettext(msg)¶

locale.dgettext(domain, msg)¶

locale.dcgettext(domain, msg, category)¶

locale.textdomain(domain)¶

locale.bindtextdomain(domain, dir)¶

locale.bind_textdomain_codeset(domain, codeset)¶

在提供此介面的系統上，locale 模組公開 C 庫的 gettext 介面。它由函式 gettext()、dgettext()、dcgettext()、textdomain()、bindtextdomain() 和 bind_textdomain_codeset() 組成。這些函式與 gettext 模組中的相同函式類似，但是對訊息目錄使用 C 庫的二進位制格式，並使用 C 庫的搜尋演算法來定位訊息目錄。

Python 應用程式通常不需要呼叫這些函式，而應使用 gettext 代替。此規則的一個已知例外是與內部呼叫 C 函式 gettext 或 dcgettext 的其他 C 庫連結的應用程式。對於這些應用程式，可能需要繫結文字域，以便庫可以正確找到其訊息目錄。

`locale` — 國際化服務¶

背景、詳細資訊、提示和注意事項¶

對於擴充套件編寫者和嵌入 Python 的程式¶

訪問訊息目錄¶

目錄

上一主題

下一主題

本頁

locale — 國際化服務¶

背景、詳細資訊、提示和注意事項¶

對於擴充套件編寫者和嵌入 Python 的程式¶

訪問訊息目錄¶

`locale` — 國際化服務¶