`locale` --- 国際化サービス¶

ソースコード: 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)¶

If locale is given and not None, setlocale() modifies the locale setting for the category. The available categories are listed in the data description below. locale may be a string, or a pair, language code and encoding. An empty string specifies the user's default settings. If the modification of the locale fails, the exception Error is raised. If successful, the new locale setting is returned.

If locale is a pair, it is converted to a locale name using the locale aliasing engine. The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding can be None.

locale が省略されたり None の場合、category の現在の設定が返されます。

以下はプログラム例です:

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
# use German locale; name and availability varies with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> 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

setlocale() is not thread-safe on most systems. Applications typically start with a call of:

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_CTYPE のロケールを一時的に LC_NUMERIC または LC_MONETARY のロケールに設定します。この一時的な変更は他のスレッドに影響します。

バージョン 3.7 で変更: 状況によっては、この関数が LC_CTYPE のロケールを一時的に LC_NUMERIC のロケールに設定するようになりました。

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¶: yes/no で答える質問への否定の応答を、regex(3) 関数で認識するために使用できる正規表現を取得します。

注釈

YESEXPR と NOEXPR の正規表現は、C ライブラリの regex 関数に適した構文を使用します。これは re の構文と異なる場合があります。

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

locale.ERA¶

ロケール内の各年代における年の数え方と表示方法を記述した文字列を取得します。

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

通常、この値を直接使用する必要はありません。書式文字列に 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¶: 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' の順に調べられます。

The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding may be None if their values cannot be determined. The "C" locale is represented as (None, None).

locale.getlocale(category=LC_CTYPE)¶

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

The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding may be None if their values cannot be determined. The "C" locale is represented as (None, 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 ロケールのエンコーディングを返します。例えば現在の LC_CTYPE ロケールがサポートされていない場合など、nl_langinfo(CODESET) が空文字列を返す場合は "utf-8" を返します。
Windows では ANSI コードページを返します。

Python の事前初期化で LC_CTYPE ロケールを設定します。ファイルシステムエンコーディングとエラーハンドラも参照してください。

この関数は getpreferredencoding(False) に似ていますが、Python UTF-8 モードを無視する点が異なります。

Added in version 3.11.

locale.normalize(localename)¶

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

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

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

現在の LC_NUMERIC 設定に従って数値 val を書式化します。書式は % 演算子の規則に従います。浮動小数点数の場合、必要に応じて小数点を変更します。 grouping が True の場合、桁区切りも反映します。

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

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

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

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 で設定された慣行に従って正規化された数値文字列に変換します。

Added in version 3.5.

locale.localize(string, grouping=False, monetary=False)¶: 正規化された数値文字列を、LC_NUMERIC 設定に従って書式化した文字列に変換します。

Added in version 3.10.

locale.atof(string, func=float)¶: string に delocalize() を適用した結果に func を適用し、LC_NUMERIC 設定に従って文字列を数値に変換します。

locale.atoi(string)¶: 文字列を LC_NUMERIC で設定された慣行に従って整数に変換します。

locale.LC_CTYPE¶

文字種を扱う関数のロケールカテゴリです。特に重要なのは、このカテゴリがテキストのエンコーディング、つまりバイト列を Unicode コードポイントとして解釈する方法を定義することです。コンテナ内の無効な設定や、リモート SSH 接続で渡される互換性のない設定による問題を避けるために、この変数が自動的に C.UTF-8 に変更される仕組みについては、PEP 538 と PEP 540 を参照してください。

Python doesn't internally use locale-dependent character transformation functions from ctype.h. Instead, 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() が返すような、オペレーティングシステムによって表示されるメッセージはこのカテゴリによって影響を受けます。

POSIX 標準に準拠していない OS、特に Windows では、この値が利用できない場合があります。

locale.LC_NUMERIC¶: Locale category for formatting numbers. The functions format_string(), 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() の返す特別な値のためのシンボル定数です。

ロケールの背景、詳細、ヒント、助言および補足説明¶

C 標準では、ロケールはプログラム全体に適用される特性で、その変更には比較的大きなコストが掛かることがあります。さらに、実装によっては不具合があり、ロケールを頻繁に変更するとコアダンプが起きる場合があります。そのため、ロケールを正しく使うのはやや厄介です。

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

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

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

ロケールに従って数値を処理する唯一の方法は、このモジュールが定義する専用の関数 atof()、atoi()、format_string()、str() を使用することです。

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

Locale names¶

The format of the locale name is platform dependent, and the set of supported locales can depend on the system configuration.

On Posix platforms, it usually has the format [1]:

     language ["_" territory] ["." charset] ["@" modifier]

where language is a two- or three-letter language code from ISO 639, territory is a two-letter country or region code from ISO 3166, charset is a locale encoding, and modifier is a script name, a language subtag, a sort order identifier, or other locale modifier (for example, "latin", "valencia", "stroke" and "euro").

On Windows, several formats are supported. [2] [3] A subset of IETF BCP 47 tags:

     language ["-" script] ["-" territory] ["." charset]
     language ["-" script] "-" territory "-" modifier

where language and territory have the same meaning as in Posix, script is a four-letter script code from ISO 15924, and modifier is a language subtag, a sort order identifier or custom modifier (for example, "valencia", "stroke" or "x-python"). Both hyphen ('-') and underscore ('_') separators are supported. Only UTF-8 encoding is allowed for BCP 47 tags.

Windows also supports locale names in the format:

     language ["_" territory] ["." charset]

where language and territory are full names, such as "English" and "United States", and charset is either a code page number (for example, "1252") or UTF-8. Only the underscore separator is supported in this format.

The "C" locale is supported on all platforms.

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

通常、Python アプリケーションがこれらの関数を呼び出す必要はなく、代わりに gettext を使用するべきです。既知の例外は、内部で C 関数の gettext や dcgettext を呼び出す追加の C ライブラリとリンクするアプリケーションです。このようなアプリケーションでは、ライブラリがメッセージカタログを正しく見つけられるように、テキストドメインのバインドが必要になる場合があります。

`locale` --- 国際化サービス¶

ロケールの背景、詳細、ヒント、助言および補足説明¶

Locale names¶

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

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

目次

前のトピックへ

次のトピックへ

このページ

locale --- 国際化サービス¶

ロケールの背景、詳細、ヒント、助言および補足説明¶

Locale names¶

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

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

`locale` --- 国際化サービス¶