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

   *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"
   になるかもしれません。

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

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


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.
