# 2 `locale` -- 国際化サービス

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

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

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

exception `Error`
  `setlocale()` が失敗したときに送出される例外です。

`setlocale`( | category[, locale])

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

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

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

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

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

  バージョン 2.0 で 変更 された仕様: 引数 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_sing_posn'` の取り得る値は 以下の通りです。

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

`nl_langinfo`( | option)

  ロケール特有の情報を文字列として返します。この関数は全てのシステムで 利用可能なわけではなく、指定できる option もプラットフォーム 間で大きく異なります。引数として使えるのは、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 で 新たに追加 された仕様です。

`getlocale`( | [category])

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

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

  バージョン 2.0 で 新たに追加 された仕様です。

`getpreferredencoding`( | [do_setlocale])

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

  システムによっては、ユーザの設定を取得するために `setlocale` を呼び出す必要があるため、この関数はスレッド安全 ではありません。`setlocale` を呼び出す必要がない、または 呼び出したくない場合、do_setlocale を `False` に 設定する必要があります。 バージョン 2.3 で 新たに追加 された仕様です。

`normalize`( | localename)

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

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

`resetlocale`( | [category])

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

  標準設定は `getdefaultlocale()` を呼ぶことで決定されます。 category は標準で `LC_ALL` になっています。 バージョン 2.0 で 新たに追加 された仕様です。

`strcoll`( | string1, string2)

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

`strxfrm`( | string)

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

`format`( | format, val[, grouping[, monetary]])

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

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

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

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

`format_string`( | format, val[, grouping])

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

  バージョン 2.5 で 新たに追加 された仕様です。

`currency`( | val[, symbol[, grouping[, international]]])

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

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

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

  バージョン 2.5 で 新たに追加 された仕様です。

`str`( | float)

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

`atof`( | string)

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

`atoi`( | string)

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

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

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

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

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

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

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

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

`CHAR_MAX`
  `localeconv()` の返す特別な値のためのシンボル定数です。

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

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

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

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

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

`T_FMT_AMPM`
  時刻を 午前／午後の書式で表現するために、 strftime(3) の 書式化文字列として用いることのできる文字列を返します。 返される値は

`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 番目の月の名前を略式表記で返します。

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

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

`YESEXPR`
  肯定／否定で答える質問に対する肯定回答を正規表現関数で 認識するために利用できる正規表現を返します。 警告: 表現は C ライブラリの `regex()` 関数 に合ったものでなければならず、これは `re` で 使われている構文とは異なるかもしれません。

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

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

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

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

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

`ERA_YEAR`
  返される値はロケールでの現年代の年値です。

`ERA_D_T_FMT`
  返される値は `strftime` で日付および時間をロケール固有の 年代に基づいた方法で表現するための書式化文字列として使うことができます。

`ERA_D_FMT`
  返される値は `strftime` で日付をロケール固有の 年代に基づいた方法で表現するための書式化文字列として使うことができます。

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

例:

    >>> import locale
    >>> loc = locale.getlocale(locale.LC_ALL) # get current locale
    >>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
    >>> 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