## 2 クラスに基づいた API

クラス形式の `gettext` モジュールのAPI は GNU gettext API よりも高い柔軟性と利便性を持っています。 Python のアプリケーションやモジュールを地域化するにはこちらを使う 方を勧めます。`gettext` では、GNU .mo 形式のファイルを 解釈し、標準の 8 ビット文字列または Unicode 文字列形式でメッセージ を返す ``翻訳'' クラスを定義しています。 この ``翻訳'' クラスのインスタンスも、組み込み名前空間に関数 `_()` として組みこみ (install) できます。

`find`( | domain[, localedir[, languages[, all]]])

  この関数は標準的な .mo ファイル検索アルゴリズムを実装 しています。`textdomain()` と同じく、domain を引数に とります。オプションの localedir は `bindtextdomain()` と同じです。またオプションの languages は文字列を列挙したリスト で、各文字列は言語コードを表します。

  localedir が与えられていない場合、標準のシステムロケール ディレクトリが使われます。29

  languages が与えられなかった場合、以下の環境変数: LANGUAGE、LC_ALL、 LC_MESSAGES、および LANG が検索されます。空でない値を返した最初の候補が languages 変数として使われます。 この環境変数は言語名をコロンで分かち書きしたリストを含んで いなければなりません。`find()` はこの文字列をコロンで 分割し、言語コードの候補リストを生成します。

  `find()` は次に言語コードを展開および正規化し、リストの 各要素について、以下のパス構成:

  localedir/language/LC_MESSAGES/domain.mo

  からなる実在するファイルの探索を反復的に行います。`find()` は上記のような実在するファイルで最初に見つかったものを返します。 該当するファイルが見つからなかった場合、`None` が返されます。 all が与えられていれば、全ファイル名のリストが言語リストまたは 環境変数で指定されている順番に並べられたものを返します。

`translation`( | domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])

  `Translations` インスタンスを domain、localedir、および languages に基づいて 生成して返します。 domain、localedir、および languages はまず 関連付けられている .mo ファイルパスのリストを取得する ために`find()` に渡されます。同じ .mo ファイル名を 持つインスタンスはキャッシュされます。実際にインスタンス化される クラスは class_ が与えられていればそのクラスが、そうでない 時には `GNUTranslations` です。クラスのコンストラクタは 単一の引数としてファイルオブジェクトを取らなくてはなりません。 codeset を指定した場合、翻訳文字列のエンコードに使う 文字セットを変更します。

  複数のファイルが発見された場合、後で見つかったファイルは前に見つかった ファイルの代替でと見なされ、後で見つかった方が利用されます。 代替の設定を可能にするには、`copy.copy` を使ってキャッシュから 翻訳オブジェクトを複製します; こうすることで、実際のインスタンスデータは キャッシュのものと共有されます。

  .mo ファイルが見つからなかった場合、fallback が偽 (標準の設定です) ならこの関数は `IOError` を送出し、 fallback が真なら `NullTranslations` インスタンスが 返されます。

  バージョン 2.4 で 変更 された仕様: codeset パラメタを追加しました

`install`( | domain[, localedir[, unicode [, codeset]]])

  `translation()` にdomain、 localedir、 およびcodeset を渡してできる関数 `_` を Python の組み込み名前空間に組み込みます。 unicode フラグは `translation()` の返す翻訳オブジェクト の `install` メソッドに渡されます。

  以下に示すように、通常はアプリケーション中の文字列を関数 `_()` の呼び出しで包み込んで翻訳対象候補であることを示します:

      print _('This string will be translated.')

  利便性を高めるためには、`_()` 関数を Python の組み込み 名前空間に組み入れる必要があります。こうすることで、アプリケーション内の 全てのモジュールからアクセスできるようになります。

  バージョン 2.4 で 新たに追加 された仕様: codeset パラメタを追加しました

#### Footnotes

... ディレクトリが使われます。29
  上の `bindtextdomain()` に関する脚注を参照してください。