# `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 の現在の設定が返されます。

  `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

    Get a string which describes how years are counted and displayed for each era in a locale.

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

    Normally it should not be necessary to use this value directly. Specifying the `E` modifier in their format strings causes the `time.strftime()` function to use this information. The format of the returned string is specified in The Open Group Base Specifications Issue 8, paragraph 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

    Get a string consisting of up to 100 semicolon-separated symbols used to represent the values 0 to 99 in a locale-specific way. In most locales this is an empty string.

  The function temporarily sets the `LC_CTYPE` locale to the locale of the category that determines the requested value (`LC_TIME`, `LC_NUMERIC`, `LC_MONETARY` or `LC_MESSAGES`) if locales are different and the resulting string is non-ASCII. This temporary change affects other threads.

  バージョン 3.14 で変更: The function now temporarily sets the `LC_CTYPE` locale in some cases.

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

  Deprecated since version 3.11, will be removed in version 3.15.

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` に設定する必要があります。

  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.

  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)

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

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

  Added in version 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_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()` の返す特別な値のためのシンボル定数です。

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

    >>> 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_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.

[1]

IEEE Std 1003.1-2024; 8.2 Internationalization Variables

[2]

UCRT Locale names, Languages, and Country/Region strings

[3]

Locale Names

## 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.