22.2. "locale" --- 国際化サービス
*********************************

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

"locale" モジュールは、 "_locale" を被うように実装されており、ANSI C
ロケール実装を使っている "_locale" が利用可能なら、こちらを先に使うよ
うになっています。

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

exception locale.Error

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

locale.setlocale(category[, locale])

   *locale* が渡され "None" でない場合、"setlocale()" は *category* の
   ロケール設定を変更します。利用可能なカテゴリーは下記の表を参照して
   ください。 *locale* は文字列か2つの文字列の iterable (言語コードと
   文字コード) です。iterale の場合 locale aliasing engine を用いてロ
   ケール名に変換されます。空の文字列はユーザのデフォルトの設定を指定
   します。ロケールの変更に失敗した場合 "Error" が送出されます。成功し
   た場合新しいロケールの設定が返されます。

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

   "setlocale()" はほとんどのシステムでスレッド安全ではありません。ア
   プリケーションを書くとき、大抵は以下のコード

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

   から書き始めます。これは全てのカテゴリをユーザの環境における標準設
   定 (大抵は環境変数 "LANG" で指定されています) に設定します。その後
   複数スレッドを使ってロケールを変更したりしない限り、問題は起こらな
   いはずです。

   バージョン 2.0 で変更: 引数 *locale* の値にイテラブルを渡せるように
   なりました。

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"     | このロケールでは特に指定しません。        |
   +----------------+-------------------------------------------+

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()" の書
      式化文字列として用いることのできる文字列を取得します。

   DAY_1 ... DAY_7

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

      注釈: ロケール US における、 "DAY_1" を日曜日とする慣行に従っ
        ていま す。国際的な (ISO 8601) 月曜日を週の初めとする慣行では
        ありませ ん。

   ABDAY_1 ... ABDAY_7

      1 週間中の n 番目の曜日名を略式表記で取得します。

   MON_1 ... MON_12

      n 番目の月の名前を取得します。

   ABMON_1 ... ABMON_12

      n 番目の月の名前を略式表記で取得します。

   locale.RADIXCHAR

      基数点 (小数点ドット、あるいは小数点コンマ、等) を取得します。

   locale.THOUSEP

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

   locale.YESEXPR

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

      注釈: 表現は C ライブラリの "regex()" 関数に合ったものでなけれ
        ばなら ず、これは "re" で使われている構文とは異なるかもしれま
        せん。

   locale.NOEXPR

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

   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 では "'LANGUAGE'" 、 "'LC_ALL'" 、
   "'LC_CTYPE'" 、および "'LANG'" の順に調べられます。

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

   バージョン 2.0 で追加.

locale.getlocale([category])

   与えられたロケールカテゴリに対する現在の設定を、 *language code* 、
   *encoding* を含むシーケンスで返します。 *category* として "LC_ALL"
   以外の "LC_*" の値の一つを指定できます。標準の設定は "LC_CTYPE" で
   す。

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

   バージョン 2.0 で追加.

locale.getpreferredencoding([do_setlocale])

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

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

   バージョン 2.3 で追加.

locale.normalize(localename)

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

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

   バージョン 2.0 で追加.

locale.resetlocale([category])

   *category* のロケールを標準設定にします。

   標準設定は "getdefaultlocale()" を呼ぶことで決定されます。
   *category* は標準で "LC_ALL" になっています。

   バージョン 2.0 で追加.

locale.strcoll(string1, string2)

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

locale.strxfrm(string)

   文字列を組み込み関数 "cmp()" で使える形式に変換し、かつロケールに則
   した結果を返します。この関数は同じ文字列が何度も比較される場合、例
   えば文字列からなるシーケンスを順序付けて並べる際に使うことができま
   す。

locale.format(format, val[, grouping[, monetary]])

   数値 *val* を現在の "LC_NUMERIC" の設定に基づいて書式化します。書式
   は "%" 演算子の慣行に従います。浮動小数点数については、必要に応じて
   浮動小数点が変更されます。 *grouping* が真なら、ロケールに配慮した
   桁数の区切りが行われます。

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

   この関数や、1文字の指定子でしか動作しないことに注意しましょう。フォ
   ーマット文字列を使う場合は "format_string()" を使用します。

   バージョン 2.5 で変更: "monetary" パラメータが追加されました。

locale.format_string(format, val[, grouping])

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

   バージョン 2.5 で追加.

locale.currency(val[, symbol[, grouping[, international]]])

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

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

   この関数は'C'ロケールでは動作しないことに注意しましょう。まず最初に
   "setlocale()" でロケールを設定する必要があります。

   バージョン 2.5 で追加.

locale.str(float)

   浮動小数点数を "str(float)" と同じように書式化しますが、ロケールに
   配慮した小数点が使われます。

locale.atof(string)

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

locale.atoi(string)

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

locale.LC_CTYPE

   文字タイプ関連の関数のためのロケールカテゴリです。このカテゴリの設
   定に従って、モジュール "string" における関数の振る舞いが変わります
   。

locale.LC_COLLATE

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

locale.LC_TIME

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

locale.LC_MONETARY

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

locale.LC_MESSAGES

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

locale.LC_NUMERIC

   数字を書式化するためのロケールカテゴリです。関数 "format()" 、
   "atoi()" 、 "atof()" および "locale" モジュールの "str()" が影響を
   受けます。他の数値書式化操作は影響を受けません。

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


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

C 標準では、ロケールはプログラム全体にわたる特性であり、その変更は高価
な処理であるとしています。加えて、頻繁にロケールを変更するようなひどい
実装はコアダンプを引き起こすこともあります。このことがロケールを正しく
利用する上で苦痛となっています。

そもそも、プログラムが起動した際、ロケールはユーザの希望するロケールに
かかわらず "C" です。プログラムは "setlocale(LC_ALL, '')" を呼び出して
、明示的にユーザの希望するロケール設定を行わなければなりません。

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

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

"string" モジュールの大小文字の変換を行う関数はロケール設定によって影
響を受けます。 "setlocale()" 関数を呼んで "LC_CTYPE" 設定を変更した場
合、変数 "string.lowercase" 、 "string.uppercase" および
"string.letters" は計算しなおされます。例えば "from string import
letters" のように、 '"from" ... "import" ...' を使ってこれらの変数を使
っている場合には、それ以降の "setlocale()" の影響を受けないので注意し
てください。

ロケールに従って数値操作を行うための唯一の方法はこのモジュールで特別に
定義されている関数: "atof()" 、 "atoi()" 、 "format()" 、 "str()" を使
うことです。


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

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

ロケールを変更するために Python コードで "locale" モジュールを使った場
合、Python を埋め込んでいるアプリケーションにも影響を及ぼします。
Python を埋め込んでいるアプリケーションに影響が及ぶことを望まない場合
、 "config.c" ファイル内の組み込みモジュールのテーブルから "_locale"
拡張モジュール  (ここで全てを行っています)  を削除し、共有ライブラリか
ら "_locale" モジュールにアクセスできないようにしてください。


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

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

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

Python アプリケーションでは、通常これらの関数を呼び出す必要はないはず
で、代わりに "gettext" を呼ぶべきです。例外として知られているのは、内
部で "gettext()" または "dcgettext()" を呼び出すような C ライブラリに
リンクするアプリケーションです。こうしたアプリケーションでは、ライブラ
リが正しいメッセージカタログを探せるようにテキストドメイン名を指定する
必要があります。
