locale --- Internationalization services

ソースコード: Lib/locale.py

---

locale モジュールは POSIX ロケールデータベースおよびロケール関連機能へのアクセスを提供します。 POSIX ロケール機構を使うことで、プログラマはソフトウェアが実行される各国における詳細を知らなくても、アプリケーション上で特定の地域文化に関係する部分を扱うことができます。

The locale module is implemented on top of the _locale module, which in turn uses an ANSI C locale implementation if available.

locale モジュールでは以下の例外と関数を定義しています:

exception locale.Error

setlocale() に渡されたロケールが認識されない場合例外が送出されます。

locale.setlocale(category, locale=None)

locale が渡され None でない場合、setlocale() は category のロケール設定を変更します。利用可能なカテゴリーは下記の表を参照してください。 locale は文字列か2つの文字列の iterable (言語コードと文字コード) です。iterale の場合 locale aliasing engine を用いてロケール名に変換されます。空の文字列はユーザのデフォルトの設定を指定します。ロケールの変更に失敗した場合 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	このロケールでは特に指定しません。

LC_NUMERIC ロケールや LC_MONETARY ロケールが LC_CTYPE ロケールと異なっていて、数値文字列や通貨文字列が非 ASCII 文字列の場合、この関数は一時的に LC_NUMERIC ロケールや LC_MONETARY ロケールに LC_CTYPE ロケールを設定します。 この一時的な変更は他のスレッドに影響を及ぼします。

バージョン 3.7 で変更: この関数は、一時的に LC_NUMERIC ロケールに LC_CTYPE ロケールを設定する場合があります。

locale.nl_langinfo(option)

ロケール特有の情報を文字列として返します。この関数は全てのシステムで利用可能なわけではなく、指定できる 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() の書式文字列として用いることのできる文字列を取得します。

locale.DAY_1

locale.DAY_2

locale.DAY_3

locale.DAY_4

locale.DAY_5

locale.DAY_6

locale.DAY_7

1 週間中の n 番目の曜日名を取得します。

注釈

ロケール US における、 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

1 週間中の 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

1000 単位桁区切り (3 桁ごとのグループ化) の区切り文字を取得します。

locale.YESEXPR

肯定／否定で答える質問に対する肯定回答を正規表現関数で認識するために利用できる正規表現を取得します。

locale.NOEXPR

Get a regular expression that can be used with the regex(3) function to recognize a negative response to a yes/no question.

注釈

The regular expressions for YESEXPR and NOEXPR use syntax suitable for the regex function from the C library, which might differ from the syntax used in re.

locale.CRNCYSTR

通貨シンボルを取得します。シンボルを値の前に表示させる場合には "-"、値の後ろに表示させる場合には "+"、シンボルを基数点と置き換える場合には "." を前につけます。

locale.ERA

現在のロケールで使われている年代を表現する値を取得します。

ほとんどのロケールではこの値を定義していません。この値を設定しているロケールの例は Japanese です。日本には日付の伝統的な表示法として、時の天皇に対応する元号名があります。

通常この値を直接指定する必要はありません。 E を書式文字列に指定することで、関数 time.strftime() がこの情報を使うようになります。返される文字列の様式は決められていないので、異なるシステム間で様式に関する同じ知識が使えると期待してはいけません。

locale.ERA_D_T_FMT

日付および時間をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ERA_D_FMT

日付をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ERA_T_FMT

時刻をロケール固有の年代に基づいた方法で表現するために、 time.strftime() の書式文字列として用いることのできる文字列を取得します。

locale.ALT_DIGITS

返される値は 0 から 99 までの 100 個の値の表現です。

locale.getdefaultlocale([envvars])

標準のロケール設定を取得しようと試み、結果をタプル (language code, encoding) の形式で返します。

POSIXによると、 setlocale(LC_ALL, '') を呼ばなかったプログラムは、移植可能な 'C' ロケール設定を使います。 setlocale(LC_ALL, '') を呼ぶことで、 LANG 変数で定義された標準のロケール設定を使うようになります。 Python では現在のロケール設定に干渉したくないので、上で述べたような方法でその挙動をエミュレーションしています。

他のプラットフォームとの互換性を維持するために、環境変数 LANG だけでなく、引数 envvars で指定された環境変数のリストも調べられます。最初に見つかった定義が使われます。 envvars は標準では GNU gettext で使われている検索順になります; これは常に変数名 LANG を探します。GNU gettext では 'LC_ALL' 、 'LC_CTYPE' 、 'LANG' 、および 'LANGUAGE' の順に調べられます。

'C' の場合を除き、言語コードは RFC 1766 に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

バージョン 3.11 で非推奨、バージョン 3.15 で削除予定.

locale.getlocale(category=LC_CTYPE)

Returns the current setting for the given locale category as sequence containing language code, encoding. category may be one of the LC_* values except LC_ALL. It defaults to LC_CTYPE.

'C' の場合を除き、言語コードは RFC 1766 に対応します。 language code および encoding が決定できなかった場合、 None になるかもしれません。

locale.getpreferredencoding(do_setlocale=True)

テキストデータに使われる ロケールエンコーディング を、ユーザの設定に基づいて返します。ユーザの設定は異なるシステム間では異なった方法で表現され、システムによってはプログラミング的に得ることができないこともあるので、この関数が返すのはただの推測です。

システムによっては、ユーザの設定を取得するために setlocale() を呼び出す必要があるため、この関数はスレッド安全ではありません。 setlocale() を呼び出す必要がない、または呼び出したくない場合、 do_setlocale を False に設定する必要があります。

On Android or if the Python UTF-8 Mode is enabled, always return 'utf-8', the locale encoding and the do_setlocale argument are ignored.

The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.

バージョン 3.7 で変更: この関数は、 Android 上あるいは Python UTF-8 モード が有効になっている場合、常に "utf-8" を返すようになりました。

locale.getencoding()

Get the current locale encoding:

• On Android and VxWorks, return "utf-8".

• On Unix, return the encoding of the current LC_CTYPE locale. Return "utf-8" if nl_langinfo(CODESET) returns an empty string: for example, if the current LC_CTYPE locale is not supported.

• On Windows, return the ANSI code page.

The Python preinitialization configures the LC_CTYPE locale. See also the filesystem encoding and error handler.

This function is similar to getpreferredencoding(False) except this function ignores the Python UTF-8 Mode.

バージョン 3.11 で追加.

locale.normalize(localename)

与えたロケール名を規格化したロケールコードを返します。返されるロケールコードは setlocale() で使うために書式化されています。規格化が失敗した場合、もとの名前がそのまま返されます。

与えたエンコードがシステムにとって未知の場合、標準の設定では、この関数は setlocale() と同様に、エンコーディングをロケールコードにおける標準のエンコーディングに設定します。

locale.resetlocale(category=LC_ALL)

Sets the locale for category to the default setting.

The default setting is determined by calling getdefaultlocale(). category defaults to LC_ALL.

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定.

locale.strcoll(string1, string2)

現在の LC_COLLATE 設定に従って二つの文字列を比較します。他の比較を行う関数と同じように、 string1 が string2 に対して前に来るか、後に来るか、あるいは二つが等しいかによって、それぞれ負の値、正の値、あるいは 0 を返します。

locale.strxfrm(string)

文字列を、ロケールを考慮した比較に使える形式に変換します。例えば、 strxfrm(s1) < strxfrm(s2) は strcoll(s1, s2) < 0 と等価です。この関数は同じ文字列が何度も比較される場合、例えば文字列からなるシーケンスを順序付けて並べる際に使うことができます。

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

Formats a number val according to the current LC_NUMERIC setting. The format follows the conventions of the % operator. For floating point values, the decimal point is modified if appropriate. If grouping is True, also takes the grouping into account.

monetary が真なら、桁区切り記号やグループ化文字列を用いて変換を行います。

format % val 形式のフォーマット指定子を、現在のロケール設定を考慮したうえで処理します。

バージョン 3.7 で変更: monetary キーワード引数が追加されました。

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

Please note that this function works like format_string() but will only work for exactly one %char specifier. For example, '%f' and '%.0f' are both valid specifiers, but '%f KiB' is not.

For whole format strings, use format_string().

バージョン 3.7 で非推奨: Use format_string() instead.

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

数値 val を、現在の LC_MONETARY の設定にあわせてフォーマットします。

symbol が真の場合は、返される文字列に通貨記号が含まれるようになります。これはデフォルトの設定です。grouping が True の場合(これはデフォルトではありません)は、値をグループ化します。international が True の場合(これはデフォルトではありません)は、国際的な通貨記号を使用します。

注釈

この関数は 'C' ロケールでは動作しないので、まず setlocale() でロケールを設定する必要があります。

locale.str(float)

Formats a floating point number using the same format as the built-in function str(float), but takes the decimal point into account.

locale.delocalize(string)

文字列を LC_NUMERIC で設定された慣行に従って正規化された数値文字列に変換します。

バージョン 3.5 で追加.

locale.localize(string, grouping=False, monetary=False)

Converts a normalized number string into a formatted string following the LC_NUMERIC settings.

バージョン 3.10 で追加.

locale.atof(string, func=float)

Converts a string to a number, following the LC_NUMERIC settings, by calling func on the result of calling delocalize() on string.

locale.atoi(string)

文字列を LC_NUMERIC で設定された慣行に従って整数に変換します。

locale.LC_CTYPE

Locale category for the character type functions. Most importantly, this category defines the text encoding, i.e. how bytes are interpreted as Unicode codepoints. See PEP 538 and PEP 540 for how this variable might be automatically coerced to C.UTF-8 to avoid issues created by invalid settings in containers or incompatible settings passed over remote SSH connections.

Python doesn't internally use locale-dependent character transformation functions from ctype.h. Instead, an internal pyctype.h provides locale-independent equivalents like Py_TOLOWER.

locale.LC_COLLATE

文字列を並べ替えるためのロケールカテゴリです。 locale モジュールの関数 strcoll() および strxfrm() が影響を受けます。

locale.LC_TIME

時刻を書式化するためのロケールカテゴリです。 time.strftime() はこのカテゴリに設定されている慣行に従います。

locale.LC_MONETARY

金額に関係する値を書式化するためのロケールカテゴリです。設定可能なオプションは関数 localeconv() で得ることができます。

locale.LC_MESSAGES

メッセージ表示のためのロケールカテゴリです。現在 Python はアプリケーション毎にロケールに対応したメッセージを出力する機能はサポートしていません。 os.strerror() が返すような、オペレーティングシステムによって表示されるメッセージはこのカテゴリによって影響を受けます。

This value may not be available on operating systems not conforming to the POSIX standard, most notably Windows.

locale.LC_NUMERIC

Locale category for formatting numbers. The functions format(), atoi(), atof() and str() of the locale module are affected by that category. All other numeric formatting operations are not affected.

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 です。例外が1つあります: LC_CTYPE カテゴリは、現在のロケールエンコーディングをユーザーの希望するロケールエンコーディングに設定するために、スタートアップで変更されます。他のカテゴリについては、プログラムは setlocale(LC_ALL, '') を呼び出して、明示的にユーザの希望するロケール設定を行わなければなりません。

setlocale() をライブラリルーチン内で呼ぶことは、それがプログラム全体に及ぼす副作用の面から、一般的によくない考えです。ロケールを保存したり復帰したりするのもよくありません: 高価な処理であり、ロケールの設定が復帰する以前に起動してしまった他のスレッドに悪影響を及ぼすからです。

もし、汎用を目的としたモジュールを作っていて、ロケールによって影響をうけるような操作 (例えば time.strftime() の書式の一部) のロケール独立のバージョンが必要ということになれば、標準ライブラリルーチンを使わずに何とかしなければなりません。よりましな方法は、ロケール設定が正しく利用できているか確かめることです。最後の手段は、あなたのモジュールが C ロケール以外の設定には互換性がないとドキュメントに書くことです。

The only way to perform numeric operations according to the locale is to use the special functions defined by this module: atof(), atoi(), format(), str().

ロケールに従ってケース変換や文字分類を行う方法はありません。 (ユニコード) テキスト文字列については、これらは文字の値のみによって行われます。その一方、バイト文字列はバイトの ASCII 値に従って変換と分類が行われます。そして、上位ビットが立っているバイト (すなわち、non-ASCII バイト) は、決して変換されず、英字や空白などの文字クラスの一部とみなされることもありません。

Python 拡張の作者と、Python を埋め込むようなプログラムに関して

拡張モジュールは、現在のロケールを調べる以外は、決して setlocale() を呼び出してはなりません。しかし、返される値もロケールの復帰のために使えるだけなので、さほど便利とはいえません (例外はおそらくロケールが C かどうか調べることでしょう)。

When Python code uses the locale module to change the locale, this also affects the embedding application. If the embedding application doesn't want this to happen, it should remove the _locale extension module (which does all the work) from the table of built-in modules in the config.c file, and make sure that the _locale module is not accessible as a shared library.

メッセージカタログへのアクセス

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)

C ライブラリの gettext インタフェースが提供されているシステムでは、 locake モジュールでそのインタフェースを公開しています。このインタフェースは関数 gettext() 、 dgettext() 、 dcgettext() 、 textdomain() 、 bindtextdomain() 、および bind_textdomain_codeset() からなります。これらは gettext モジュールの同名の関数に似ていますが、メッセージカタログとして C ライブラリのバイナリフォーマットを使い、メッセージカタログを探すために C ライブラリのサーチアルゴリズムを使います。

Python applications should normally find no need to invoke these functions, and should use gettext instead. A known exception to this rule are applications that link with additional C libraries which internally invoke C functions gettext or dcgettext. For these applications, it may be necessary to bind the text domain, so that the libraries can properly locate their message catalogs.