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

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

locale モジュールは POSIX のロケールデータベースと関連機能へのアクセスを提供します。 POSIX のロケール機構を使うと、ソフトウェアが実行される国ごとの事情をすべて知っていなくても、アプリケーション内で文化的な違いの一部に対応できます。

locale モジュールは _locale モジュール上に実装されています。後者は、利用できる場合に ANSI C のロケール実装を使用します。

locale モジュールは次の例外と関数を定義しています。

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

locale.setlocale(category, locale=None)¶

locale が指定され、None でない場合、setlocale() は category のロケール設定を変更します。利用できるカテゴリは、後述のデータの説明に一覧があります。 locale には文字列または言語コードとエンコーディングのペアを指定できます。空文字列はユーザーのデフォルト設定を指定します。ロケールの変更に失敗すると Error を送出します。成功すると、新しいロケール設定を返します。

locale がペアの場合、ロケールの別名を処理する機構でロケール名に変換されます。言語コードは、エンコーディングを除けばロケール名と同じ形式です。言語コードとエンコーディングには None も指定できます。

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

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

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # 現在のロケールを取得する
# ドイツ語ロケールを使う。
# 名前と利用可否はプラットフォームによって異なる。
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> locale.strcoll('f\xe4n', 'foo')  # ウムラウトを含む文字列を比較する
>>> locale.setlocale(locale.LC_ALL, '')   # ユーザーが選択したロケールを使う
>>> locale.setlocale(locale.LC_ALL, 'C')  # デフォルトの C ロケールを使う
>>> locale.setlocale(locale.LC_ALL, loc)  # 保存したロケールに戻す

ほとんどのシステムで setlocale() はスレッドセーフではありません。通常、アプリケーションは最初に次の呼び出しを行います。

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

これにより、すべてのカテゴリのロケールがユーザーのデフォルト設定 (通常は環境変数 LANG で指定) になります。その後ロケールを変更しなければ、複数のスレッドを使っても問題は起こらないはずです。

バージョン 3.15 で変更: @ 修飾子付きの言語コードをサポートしました。

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 個の記号からなる文字列を取得します。ほとんどのロケールでは空文字列です。

要求された値を決めるカテゴリ (LC_TIME、LC_NUMERIC、LC_MONETARY、LC_MESSAGES) と LC_CTYPE のロケールが異なり、結果の文字列に非 ASCII 文字が含まれる場合、この関数は LC_CTYPE のロケールをそのカテゴリのロケールに一時的に設定します。この一時的な変更は他のスレッドに影響します。

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

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' の順に調べられます。

言語コードは、エンコーディングと @ 修飾子を除けばロケール名と同じ形式です。値を判定できない場合、言語コードやエンコーディングは None になることがあります。 "C" ロケールは (None, None) で表されます。

locale.getlocale(category=LC_CTYPE)¶

指定されたロケールカテゴリの現在の設定を、言語コードとエンコーディングからなるタプルで返します。 category には、LC_ALL を除く LC_* の値を指定できます。デフォルトは LC_CTYPE です。

言語コードは、エンコーディングを除けばロケール名と同じ形式です。値を判定できない場合、言語コードやエンコーディングは None になることがあります。 "C" ロケールは (None, None) で表されます。

バージョン 3.15 で変更: @ 修飾子を黙って取り除くことをやめ、言語コードに含めるようになりました。

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 は内部で ctype.h のロケール依存の文字変換関数を使用しません。代わりに、pyctype.h が 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 モジュールの format_string()、atoi()、atof()、str() がこのカテゴリの影響を受けます。それ以外の数値の書式化操作には影響しません。

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 バイト) は、決して変換されず、英字や空白などの文字クラスの一部とみなされることもありません。

ロケール名¶

ロケール名の形式はプラットフォームに依存し、サポートされるロケールの集合はシステムの構成によって異なる場合があります。

POSIX プラットフォームでは、通常は次の形式です [1]。

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

ここで language は ISO 639 の 2 文字または 3 文字の言語コード、territory は ISO 3166 の 2 文字の国・地域コード、charset はロケールエンコーディングです。 modifier は、文字体系名、言語サブタグ、照合順序の識別子、またはその他のロケール修飾子です (例: "latin"、"valencia"、"stroke"、"euro")。

Windows はいくつかの形式をサポートしています [2] [3]。 IETF BCP 47 タグのサブセットは次の形式です。

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

ここで language と territory の意味は POSIX と同じです。 script は ISO 15924 の 4 文字の文字体系コードで、modifier は言語サブタグ、照合順序の識別子、またはカスタムの修飾子です (例: "valencia"、"stroke"、"x-python")。区切りにはハイフン ('-') とアンダースコア ('_') の両方が使えます。 BCP 47 タグで使用できるエンコーディングは UTF-8 のみです。

Windows は次の形式のロケール名もサポートしています。

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

ここで language と territory は "English"、"United States" などの完全な名前で、charset はコードページ番号 (例: "1252") または UTF-8 です。この形式では、区切りにアンダースコアのみを使用できます。

"C" ロケールはすべてのプラットフォームでサポートされています。

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

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

Python コードが locale モジュールでロケールを変更すると、Python を埋め込んでいるアプリケーションにも影響します。それを避けたい場合は、実際の処理を行う _locale 拡張モジュールを config.c の組み込みモジュールの表から取り除き、共有ライブラリとしても _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)¶

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

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

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

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

ロケール名¶

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

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

目次

前のトピックへ

次のトピックへ

このページ

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

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

ロケール名¶

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

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

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