
:mod:`locale` --- 国際化サービス
================================

.. module:: locale
   :synopsis: 国際化サービス。
.. moduleauthor:: Martin von Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin von Löwis <martin@v.loewis.de>


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

.. index:: module: _locale

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

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


.. exception:: Error

   :func:`setlocale` が失敗したときに送出される例外です。


.. function:: setlocale(category[, locale])

   *locale* を指定する場合、文字列、 ``(language code, encoding)`` 、からなるタプル、または ``None``
   をとることができます。 *locale* がタプルのの場合、ロケール別名解決エンジンによって文字列に変換されます。 *locale* が与えられていて、かつ
   ``None`` でない場合、 :func:`setlocale` は *category* の設定を変更します。
   変更することのできるカテゴリは以下に列記されており、値はロケール設定の名前です。空の文字列を指定すると、ユーザの環境における標準設定になります。
   ロケールの変更に失敗した場合、 :exc:`Error` が送出されます。成功した場合、新たなロケール設定が返されます。

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

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

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

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

   .. versionchanged:: 2.0
      引数 *locale* の値としてタプルをサポートしました。


.. function:: localeconv()

   地域的な慣行のデータベースを辞書として返します。辞書は以下の文字列をキーとして持っています:

   +----------------------+-------------------------------------+--------------------------------------------------------------------+
   | カテゴリ             | キー名                              | 意味                                                               |
   +======================+=====================================+====================================================================+
   | :const:`LC_NUMERIC`  | ``'decimal_point'``                 | 小数点を表す文字です。                                             |
   +----------------------+-------------------------------------+--------------------------------------------------------------------+
   |                      | ``'grouping'``                      | ``'thousands_sep'``                                                |
   |                      |                                     | が来るかもしれない場所を相対的に                                   |
   |                      |                                     | 表した数からなる配列です。配列が                                   |
   |                      |                                     | :const:`CHAR_MAX` で終端されている                                 |
   |                      |                                     | 場合、それ以上の桁では桁数字のグループ化を行いません。配列が       |
   |                      |                                     | ``0``                                                              |
   |                      |                                     | で終端されている場合、最後に指定したグループが反復的に使われます。 |
   +----------------------+-------------------------------------+--------------------------------------------------------------------+
   |                      | ``'thousands_sep'``                 | 桁グループ間を区切るために使われる文字です。                       |
   +----------------------+-------------------------------------+--------------------------------------------------------------------+
   | :const:`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'``       | 符号の位置です                                                     |
   |                      |                                     | (それぞれ正の値と負の値を表します)。以下を参照ください。           |
   +----------------------+-------------------------------------+--------------------------------------------------------------------+

   数値形式の値に :const:`CHAR_MAX` を設定すると、そのロケールでは値が指定されていないことを表します。

   ``'p_sign_posn'`` および ``'n_sing_posn'`` の取り得る値は以下の通りです。

   +--------------+----------------------------------------+
   | 値           | 説明                                   |
   +==============+========================================+
   | ``0``        | 通貨記号および値は丸括弧で囲われます。 |
   +--------------+----------------------------------------+
   | ``1``        | 符号は値と通貨記号より前に来ます。     |
   +--------------+----------------------------------------+
   | ``2``        | 符号は値と通貨記号の後に続きます。     |
   +--------------+----------------------------------------+
   | ``3``        | 符号は値の直前に来ます。               |
   +--------------+----------------------------------------+
   | ``4``        | 符号は値の直後に来ます。               |
   +--------------+----------------------------------------+
   | ``CHAR_MAX`` | このロケールでは特に指定しません。     |
   +--------------+----------------------------------------+


.. function:: nl_langinfo(option)

   ロケール特有の情報を文字列として返します。この関数は全てのシステムで利用可能なわけではなく、指定できる *option* もプラットフォーム
   間で大きく異なります。引数として使えるのは、locale モジュールで利用可能なシンボル定数を表す数字です。

   関数 :func:`nl_langinfo` は以下のキーのうち一つを受理します。ほとんどの記述は GNU C
   ライブラリ中の対応する説明から引用されています。

   .. data:: CODESET

      選択されたロケールで用いられている文字エンコーディングの名前を文字列で取得します。

   .. data:: D_T_FMT

      時刻および日付をロケール特有の方法で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: D_FMT

      日付をロケール特有の方法で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: T_FMT

      時刻をロケール特有の方法で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: T_FMT_AMPM

      時刻を午前／午後の書式で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: DAY_1 ... DAY_7

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

      .. note::

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

   .. data:: ABDAY_1 ... ABDAY_7

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

   .. data:: MON_1 ... MON_12

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

   .. data:: ABMON_1 ... ABMON_12

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

   .. data:: RADIXCHAR

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

   .. data:: THOUSEP

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

   .. data:: YESEXPR

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

      .. note::

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

   .. data:: NOEXPR

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

   .. data:: CRNCYSTR

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

   .. data:: ERA

      現在のロケールで使われている年代を表現する値を取得します。

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

      通常この値を直接指定する必要はありません。 ``E`` を書式化文字列に指定することで、関数 :func:`strftime` がこの情報を使うようになります。
      返される文字列の様式は決められていないので、異なるシステム間で様式に関する同じ知識が使えると期待してはいけません。

   .. data:: ERA_D_T_FMT

      日付および時間をロケール固有の年代に基づいた方法で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: ERA_D_FMT

      日付をロケール固有の年代に基づいた方法で表現するために、 :func:`strftime` の書式化文字列として用いることのできる文字列を取得します。

   .. data:: ALT_DIGITS

      返される値は 0 から 99 までの 100 個の値の表現です。


.. function:: getdefaultlocale([envvars])

   標準のロケール設定を取得しようと試み、結果をタプル ``(language code, encoding)`` の形式で返します。
   POSIXによると、 ``setlocale(LC_ALL, '')`` を呼ばなかったプログラムは、移植可能な ``'C'`` ロケール設定を使います。
   ``setlocale(LC_ALL, '')`` を呼ぶことで、 :envvar:`LANG` 変数で定義された標準のロケール設定を使うようになります。
   Python では現在のロケール設定に干渉したくないので、上で述べたような方法でその挙動をエミュレーションしています。

   他のプラットフォームとの互換性を維持するために、環境変数 :envvar:`LANG` だけでなく、引数 *envvars* で指定された環境変数のリスト
   も調べられます。 *envvars* は標準では GNU gettext で使われているサーチパスになります; パスには必ず変数名 ``LANG`` が含まれて
   いるからです。GNU gettext サーチパスは ``'LANGUAGE'`` 、 ``'LC_ALL'`` 、 ``'LC_CTYPE'`` 、および
   ``'LANG'`` が列挙した順番に含まれています。

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

   .. versionadded:: 2.0


.. function:: getlocale([category])

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

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

   .. versionadded:: 2.0


.. function:: getpreferredencoding([do_setlocale])

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

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

   .. versionadded:: 2.3


.. function:: normalize(localename)

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

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

   .. versionadded:: 2.0


.. function:: resetlocale([category])

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

   標準設定は :func:`getdefaultlocale` を呼ぶことで決定されます。 *category* は標準で :const:`LC_ALL`
   になっています。

   .. versionadded:: 2.0


.. function:: strcoll(string1, string2)

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


.. function:: strxfrm(string)

   .. index:: builtin: cmp

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


.. function:: format(format, val[, grouping[, monetary]])

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

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

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

   .. versionchanged:: 2.5
      *monetary* パラメータが追加されました.


.. function:: format_string(format, val[, grouping])

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

   .. versionadded:: 2.5


.. function:: currency(val[, symbol[, grouping[, international]]])

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

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

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

   .. versionadded:: 2.5


.. function:: str(float)

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


.. function:: atof(string)

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


.. function:: atoi(string)

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


.. data:: LC_CTYPE

   .. index:: module: string

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


.. data:: LC_COLLATE

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


.. data:: LC_TIME

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


.. data:: LC_MONETARY

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


.. data:: LC_MESSAGES

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


.. data:: LC_NUMERIC

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


.. data:: LC_ALL

   全てのロケール設定を総合したものです。ロケールを変更する際にこのフラグが使われた場合、そのロケールにおける全てのカテゴリを設定
   しようと試みます。一つでも失敗したカテゴリがあった場合、全てのカテゴリにおいて設定変更を行いません。このフラグを使ってロケールを
   取得した場合、全てのカテゴリにおける設定を示す文字列が返されます。この文字列は、後に設定を元に戻すために使うことができます。


.. data:: CHAR_MAX

   :func:`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`` です。プログラムは ``setlocale(LC_ALL,
'')`` を呼び出して、明示的にユーザの希望するロケール設定を行わなければなりません。

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

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

.. index:: module: string

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

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


.. _embedding-locale:

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

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

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


.. _locale-gettext:

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

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

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

