repo_zf1/documentation/manual/ja/module_specs/Zend_Locale-Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.locale.introduction">

    <title>導入</title>

    <para>
        <classname>Zend_Locale</classname> は、
        "ひとつのアプリケーションを世界中で使用するにはどうしたらいいでしょう?"
        という質問に対するフレームワーク側からの回答です。たいていの人は
        "かんたんじゃん。出力内容をいくつかの言語に翻訳すればいいんだよ。"
        と言うでしょう。
        しかし、ただ単にフレーズを他の言語に置き換えるだけといった単純な翻訳テーブルでは不十分です。
        たとえば姓と名の順番や敬称、そして数値や日付、時刻、通貨などの書式は、
        地域によって異なります。
    </para>

    <para>
        <ulink url="http://en.wikipedia.org/wiki/L10n">地域化 (Localization)</ulink>
        だけでなく、
        <ulink url="http://en.wikipedia.org/wiki/L10n">国際化 (Internationalization)</ulink>
        も必要となります。これらは、それぞれ <code>L10n</code> および <code>I18n</code>
        と略されることもあります。国際化とは、そのシステムを特定のユーザ集団の
        (言語、地域、数値書式、財務規約、日付時刻書式などの)
        ニーズにかかわらず使用できるようにすることを言います。
        地域化とは、特定の集団のニーズに対応するために、
        システムに明示的なサポートを追加することを言います。
        たとえば言語の翻訳や、各地域の規約 (複数形の扱い、日付、時刻、通貨、名前、
        記号、並び順など) が該当します。
        <code>L10n</code> と <code>I18n</code> は、お互い補完しあうものです。
        Zend Framework では、いくつかのコンポーネントを組み合わせることで
        これらのサポートを提供しています。たとえば <classname>Zend_Locale</classname>、<classname>Zend_Date</classname>、
        <classname>Zend_Measure</classname>、<classname>Zend_Translate</classname>、<classname>Zend_Currency</classname>
        そして <classname>Zend_TimeSync</classname> といったコンポーネントがあります。
    </para>

    <tip>
        <title>Zend_Locale と setLocale()</title>
        <para>
            <ulink url="http://php.net/setlocale">PHP のドキュメント</ulink>
            には、<code>setlocale()</code> はプロセス単位で動作するのでスレッドセーフではないと書かれています。
            つまり、マルチスレッド環境では「スクリプト内で一切ロケールを変更していないのに、
            勝手にロケールが変わってしまう」といった問題が発生する可能性があるということです。
            スクリプトで <code>setlocale()</code> を使用すると、予期せぬ挙動を引き起こすことがあります。
        </para>
        <para>
            <classname>Zend_Locale</classname> にはこのような制限はありません。なぜなら
            <classname>Zend_Locale</classname> は PHP の <code>setlocale()</code>
            を使用しているわけではないからです。
        </para>
    </tip>

    <sect2 id="zend.locale.whatislocalization">

        <title>地域化とは</title>

        <para>
            地域化とは、あるアプリケーション (あるいはホームページ)
            が、さまざまな言語を話すユーザによって使用することができるということです。
            しかし、ご存知のとおり、地域化とは単に文字列を翻訳するだけのことではありません。
            以下のような内容が含まれます。
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <classname>Zend_Locale</classname> -
                    他の ZF コンポーネントにおける地域化サポートで対応しているロケールのバックエンドとなります。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Translate</classname> - 文字列を翻訳します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Date</classname> - 日付や時刻を地域化します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Calendar</classname> -
                    カレンダーを地域化します (グレゴリオ暦以外の暦もサポートしています)。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Currency</classname> - 通貨を地域化します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Locale_Format</classname> - 地域化された数値のパースおよび生成を行います。
                </para>
            </listitem>
            <listitem>
                <para>
                    <classname>Zend_Locale_Data</classname> -
                    国名や言語名、そして
                    <ulink url="http://unicode.org/cldr/">CLDR にあるさまざまな内容</ulink>
                    について、各地域の標準文字列を取得します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>TODO</code> - Localization of collations
                </para>
            </listitem>
        </itemizedlist>

    </sect2>

    <sect2 id="zend.locale.whatis">

        <title>
            <ulink url="http://unicode.org/reports/tr35/#Locale">ロケールとは?</ulink>
        </title>

        <para>
            コンピュータのユーザは皆、(気づいていないかもしれませんが) ロケールを使用しています。
            地域化をサポートしていないアプリケーションの場合は、
            通常は暗黙的に特定のロケール (そのアプリケーションの作者のロケール)
            を使用しています。
            クラスや関数が地域化されていることを、ここでは
            <code>ロケールに対応している</code>ということにします。
            そのユーザがどの地域にいるのかを、どうやってコードで知るのでしょうか?
        </para>

        <para>
            ロケール文字列あるいはロケールを表すオブジェクトを使用して、
            <classname>Zend_Locale</classname> およびそのサブクラスはユーザが希望する言語および地域を知ります。
            この情報にもとづいて、正しい書式化や正規化、規約を適用します。
        </para>

    </sect2>

    <sect2 id="zend.locale.representation">

        <title>ロケールの表現方法は?</title>

        <para>
            ロケール識別子に含まれる情報は、ユーザの言語と
            地理上の地域 (たとえば自宅あるいは勤務先の属する州など) です。
            Zend Framework が使用するロケール識別文字列は、
            国際的に定義されている言語と地域の略称で、
            <code>language_REGION</code> という形式です。
            言語および地域は、どちらも ASCII 文字列となります。
        </para>

        <note>
            <para>
                大半の人の予想に反して、実はロケールは 2 文字とは限りません。
                言語についても地域についても、短縮形が 2 文字にならないものがあります。
                したがって、地域や言語の切り出しは自前では行わないようにしましょう。
                ロケール文字列から言語や地域を切り出したい場合は <classname>Zend_Locale</classname> を使用しましょう。
                自前で行ってしまうと、予期せぬ結果となってしまうことがあります。
            </para>
        </note>

        <para>
            アメリカのユーザの言語は <code>英語</code>、そして地域は <code>アメリカ</code>
            です。そこで、ロケール識別子は "en_US" となります。
            ドイツのユーザの言語は <code>ドイツ</code>、そして地域は <code>ドイツ</code>
            です。そこで、ロケール識別子は "de_DE" となります。
            <ulink url="http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html">
            ロケールおよび地域の組み合わせの定義済みの一覧</ulink>
            を参考に、Zend Framework で使用するロケールを選択しましょう。
        </para>

        <example id="zend.locale.representation.example-1">
            <title>特定のロケールの選択</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_DE'); // ドイツ語 _ ドイツ
]]>
            </programlisting>
        </example>

        <para>
            アメリカに住むドイツ人は、言語は <code>ドイツ語</code> で地域は <code>アメリカ</code>
            としたいかも知れません。しかし、このような非標準の組み合わせは、
            "ロケール" としては直接サポートしていません。
            そのかわりに、もし無効な組み合わせが使用されると、
            自動的に地域コードが切り捨てられます。
            たとえば "de_IS" は "de" に切り捨てられ、"xh_RU" は "xh"
            に切り捨てられます。これらの組み合わせは無効だからです。
            さらに、言語コードがサポートされていない場合 (例 "zz_US")
            や存在しない場合は、デフォルトの "root" ロケールを使用します。
            "root" ロケールではデフォルトとして、
            国際的に認知されている日付、時刻、数値、通過等を定義しています。
            この切捨て処理は、要求された情報の内容に依存します。
            言語と地域の組み合わせの中には、
            特定の型のデータ (たとえば日付) では有効だけれども
            別の型 (たとえば通貨) では無効だというものがあるからです。
        </para>

        <para>
            過去の歴史には注意しましょう。ZF コンポーネントは、
            これまでさまざまな場所で変更されてきた過去のタイムゾーンについては対応しません。
            たとえば
            <ulink url="http://www.statoids.com/tus.html">この一覧表</ulink>
            をご覧ください。特定の地域が夏時間を採用するかどうかや、
            どのタイムゾーンに属するかなどは、時の政府によって何度も変更されています。
            したがって、日付の計算をおこなう際には、
            ZF コンポーネントはこれらの変更には対応しません。
            その代わりに、現時点の夏時間対応、現時点のタイムゾーンに対応した正しい時刻を使用します。
        </para>

    </sect2>

    <sect2 id="zend.locale.selection">

        <title>正しいロケールの選択</title>

        <para>
            たいていの場合は、<code>new Zend_Locale()</code>
            とすると自動的に正しいロケールを選択します。
            これはユーザのウェブブラウザから送られてきた情報をもとに判断します。
            しかし、<code>new Zend_Locale(Zend_Locale::ENVIRONMENT)</code>
            を使用すると、以下に示すようにホストサーバの環境設定から情報を取得するようになります。
        </para>

        <example id="zend.locale.selection.example-1">
            <title>ロケールの自動選択</title>
            <programlisting role="php"><![CDATA[
$locale  = new Zend_Locale();

// デフォルトの挙動で、上と同じです
$locale1 = new Zend_Locale(Zend_Locale::BROWSER);

// ホストサーバ上の設定を使用します
$locale2 = new Zend_Locale(Zend_Locale::ENVIRONMENT);

// フレームワークアプリケーションのデフォルト設定を使用します
$locale3 = new Zend_Locale(Zend_Locale::FRAMEWORK);
]]>
            </programlisting>
        </example>

        <para>
            <classname>Zend_Locale</classname> がロケールの自動選択に使用する検索アルゴリズムは、
            三種類の情報をもとにしています。
            <orderedlist>
                <listitem>
                    <para>
                        const <classname>Zend_Locale::BROWSER</classname> -
                        ユーザのウェブブラウザは、リクエストの際に情報を送信します。これは、
                        PHP のグローバル変数 <code>HTTP_ACCEPT_LANGUAGE</code> で取得できます。
                        対応するロケールが見つからない場合は <code>ENVIRONMENT</code>
                        による検索を行い、それでもだめなら最後は
                        <code>FRAMEWORK</code> を使用します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        const <classname>Zend_Locale::ENVIRONMENT</classname> -
                        PHP は、ホストサーバのロケールを
                        <code>setlocale()</code> 関数で取得します。
                        対応するロケールが見つからない場合は <code>FRAMEWORK</code> による検索を行い、
                        それでもだめなら最後は <code>BROWSER</code> を使用します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        const <classname>Zend_Locale::FRAMEWORK</classname> -
                        Zend Framework がコンポーネントのデフォルトを指定できる仕組みが定まったら
                        (予定されていますが、現在はまだありません)、
                        この定数を使用することでデフォルト設定を選択できるようになります。
                        対応するロケールが見つからない場合は <code>ENVIRONMENT</code>
                        による検索を行い、それでもだめなら最後は
                        <code>BROWSER</code> を使用します。
                    </para>
                </listitem>
            </orderedlist>
        </para>

    </sect2>


    <sect2 id="zend.locale.selection.automatic">

        <title>自動ロケールの使用法</title>

        <para>
            <classname>Zend_Locale</classname> では、さらに 3 つのロケールを用意しています。
            これらのロケールは、どこか特定の言語や地域を表すものではありません。
            これらは "自動" ロケール、つまり
            <code>getDefault()</code> メソッドと同じような働きをするものです。
            しかし、インスタンスを作成したりといった余計な作業が不要になります。
            これらの "自動" ロケールは、標準のロケールを使用できるところなら
            どこででも使用可能で、文字列で指定することになります。
            これを使用することで、ブラウザが提供するロケール情報などをうまく利用できるようになります。
        </para>

        <para>
            以下の 3 つのロケールは、それぞれ微妙に異なる働きをします。

            <orderedlist>
                <listitem>
                    <para>
                        <code>'browser'</code> - <classname>Zend_Locale</classname>
                        は、ユーザが使用するウェブブラウザが提供する情報を使用します。
                        これは、PHP のグローバル変数 <code>HTTP_ACCEPT_LANGUAGE</code>
                        で取得します。
                    </para>
                    <para>
                        ブラウザが複数のロケールを指定している場合は、
                        <classname>Zend_Locale</classname> は最初に見つけたロケールを使用します。
                        ブラウザがロケールを指定していなかったり、
                        あるいはコマンドラインからスクリプトを実行したりした場合は、
                        代わりに自動ロケール <code>'environment'</code>
                        を使用してその結果を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>'environment'</code> - <classname>Zend_Locale</classname> は、
                        サーバが提供する情報を使用します。これは、PHP の内部関数
                        <code>setlocale()</code> で取得します。
                    </para>
                    <para>
                        複数のロケールを指定している場合は、
                        <classname>Zend_Locale</classname> は最初に見つけたロケールを使用します。
                        サーバがロケールを指定していない場合は、
                        代わりに自動ロケール <code>'browser'</code>
                        を使用してその結果を返します。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>'auto'</code> - <classname>Zend_Locale</classname> は、
                        可能な限りの方法でロケールを検出しようとします。
                        まず最初にユーザが指定するロケールを探し、
                        それに失敗するとホストのロケールを探します。
                    </para>
                    <para>
                        ロケールの検出に失敗した場合は例外をスローし、
                        自動検出に失敗したことを通知します。
                    </para>
                </listitem>
            </orderedlist>
        </para>

        <example id="zend.locale.selection.automatic.example-1">
            <title>自動ロケールの使用法</title>
            <programlisting role="php"><![CDATA[
// 自動検出なし
//$locale = new Zend_Locale(Zend_Locale::BROWSER);
//$date = new Zend_Date($locale);

// 自動検出つき
$date = new Zend_Date('auto');
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.defaultlocale">

        <title>デフォルトのロケールの使用</title>

        <para>
            環境によっては、ロケールの自動検出ができないこともあります。
            コマンドラインからのリクエストを受け取った場合や
            リクエスト元のブラウザに言語が設定されていない場合、
            そしてサーバ上のロケールが 'C'
            あるいはその他のプロプライエタリなロケールだったりする場合などです。
        </para>

        <para>
            このような場合は、<classname>Zend_Locale</classname>
            は通常は例外をスローして自動検出に失敗したことを示します。
            このような状況への対応方法は二通りあります。
            新たなロケールを手動で設定するか、あるいはデフォルトのロケールを定義するかです。
        </para>

        <example id="zend.locale.defaultlocale.example-1">
            <title>ロケールの例外処理</title>
            <programlisting role="php"><![CDATA[
// 起動ファイル内で
try {
    $locale = new Zend_Locale('auto');
} catch (Zend_Locale_Exception $e) {
    $locale = new Zend_Locale('de');
}

// モデル/コントローラ内で
$date = new Zend_Date($locale);
]]>
            </programlisting>
        </example>

        <para>
            この方法には大きな問題点があります。<classname>Zend_Locale</classname>
            を使用するすべてのクラス内で、ロケールオブジェクトを設定することになるのです。
            複数のクラスを使用している場合など、これはとても面倒です。
        </para>

        <para>
            Zend Framework リリース 1.5 以降では、もっとうまいやりかたが用意されています。
            デフォルトのロケールを、静的メソッド <code>setDefault()</code> で設定できるのです。
            もちろん、未知のロケールや不完全なロケールが指定された場合も例外をスローします。
            <code>setDefault()</code> は、<classname>Zend_Locale</classname>
            を使用するクラスのインスタンスを作成する前に最初にコールする必要があります。
            詳細は、次の例を参照ください。
        </para>

        <example id="zend.locale.defaultlocale.example-2">
            <title>デフォルトのロケールの設定</title>
            <programlisting role="php"><![CDATA[
// 起動ファイル内で
Zend_Locale::setDefault('de');

// モデル/コントローラ内で
$date = new Zend_Date();
]]>
            </programlisting>
        </example>

        <para>
            ロケールが検出できなかった場合は、自動的にロケール
            <emphasis role="strong">de</emphasis> を使用します。
            見つかった場合は、そのロケールを使用します。
        </para>

    </sect2>

    <sect2 id="zend.locale.interoperate">

        <title>ZF のロケール対応のクラス</title>

        <para>
            ZF では、ロケール対応のクラスは <classname>Zend_Locale</classname>
            を使用しています。そして、上で説明したように自動的にロケールを選択します。
            たとえば、ZF のウェブアプリケーションで <classname>Zend_Date</classname>
            を使用して日付を作成すると、何もロケールを指定しなくても
            ユーザのウェブブラウザの設定からロケール情報を取得してそれを使用します。
        </para>

        <example id="zend.locale.interoperate.example-1">
            <title>日付のデフォルトが、ウェブのユーザのロケールになる例</title>
            <programlisting role="php"><![CDATA[
$date = new Zend_Date('2006',Zend_Date::YEAR);
]]>
            </programlisting>
        </example>

        <para>
            このデフォルトを上書きし、ロケール対応の ZF
            コンポーネントでウェブサイトの訪問者の設定にかかわらず特定のロケールを指定するには、
            コンストラクタの三番目の引数でロケールを明示的に指定します。
        </para>

        <example id="zend.locale.interoperate.example-2">
            <title>デフォルトのロケール選択のオーバーライド</title>
            <programlisting role="php"><![CDATA[
$usLocale = new Zend_Locale('en_US');
$date = new Zend_Date('2006',Zend_Date::YEAR, $usLocale);
$temp = new Zend_Measure_Temperature('100,10',
                                     Zend_Measure::TEMPERATURE,
                                     $usLocale);
]]>
            </programlisting>
        </example>

        <para>
            多くのオブジェクトですべて同一のデフォルトロケールを使用することがわかっている場合は、
            それを明示的に指定すると、毎回デフォルトロケールを検索することによる
            オーバーヘッドを回避することができます。
        </para>

        <example id="zend.locale.interoperate.example-3">
            <title>デフォルトのロケールを使用する際のパフォーマンスの最適化</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale();
$date = new Zend_Date('2006', Zend_Date::YEAR, $locale);
$temp = new Zend_Measure_Temperature('100,10',
                                     Zend_Measure::TEMPERATURE,
                                     $locale);
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.frameworkwidelocale">

        <title>アプリケーション単位のロケール</title>

        <para>
            Zend Framework ではアプリケーション単位でのロケールの使用も可能です。
            そのためには、<classname>Zend_Locale</classname> のインスタンスをレジストリに
            'Zend_Locale' というキーで登録します。すると、Zend Framework
            のロケール対応のクラスすべてがこのインスタンスを使うようになります。
            このようにして一度レジストリにロケールを設定してしまえば、
            あとでまた設定しなおす手間が省けます。
            他のすべてのクラスでも自動的にこれが用いられるようになります。
            具体的な使用法は、以下の例を参照ください。
        </para>

        <example id="zend.locale.frameworkwidelocale.example">
            <title>アプリケーション単位のロケールの使用例</title>
            <programlisting role="php"><![CDATA[
// 起動ファイルで
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// モデルあるいはコントローラ内で
$date = new Zend_Date();
// print $date->getLocale();
echo $date->getDate();
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.formatoptions">

        <title>Zend_Locale_Format::setOptions(array $options)</title>

        <para>
            オプション 'precision' の値を使用して、桁数の切り詰めあるいは拡張を行います。
            '-1' を指定すると、値の小数部分の桁数を変更しないようにします。
            オプション 'locale' は、数値や日付をパースする際の区切り文字や月名を判断するために使用します。
            オプション 'format_type' では、CLDR/ISO 日付書式指定トークンおよび PHP
            の date() で使用するトークンのどちらを使用するかを選択します。
            オプション 'fix_date' は、無効な形式の日付に対する自動修正処理を有効あるいは無効にします。
            オプション 'number_format' は、<code>toNumber()</code>
            で使用するデフォルトの数値書式を指定します
            (詳細は <xref linkend= "zend.locale.number.localize"/> を参照ください)。
        </para>

        <para>
            'date_format' オプションでデフォルトの日付書式文字列を指定することができます。
            しかし、setOptions() で 'date_format' を指定した後で getDate() や
            checkdateFormat() そして getTime() を使用する際には十分注意しましょう。
            これらのメソッドをそのロケールのデフォルトの日付書式で使用するには
            array('date_format' => null, 'locale' => $locale) をメソッドのオプションで指定します。
        </para>

        <example id="zend.locale.formatoptions.example-1">
            <title>日付のデフォルトを、ウェブユーザの正しいロケールに設定する</title>
            <programlisting role="php"><![CDATA[
Zend_Locale_Format::setOptions(array('locale' => 'en_US',
                                     'fix_date' => true,
                                     'format_type' => 'php'));
]]>
            </programlisting>
        </example>

        <para>
            ロケールの標準の定義を使用する場合は、オプション <classname>Zend_Locale_Format::STANDARD</classname>
            を指定します。<code>date_format</code> に <classname>Zend_Locale_Format::STANDARD</classname> を設定すると、
            実際に設定されているロケールの標準定義を使用します。
            これを number_format に設定すると、このロケールの標準数値書式を使用します。
            また、locale に設定すると、この環境あるいはブラウザの標準のロケールを使用します。
        </para>

        <example id="zend.locale.formatoptions.example-2">
            <title>setOptions() での STANDARD の使用</title>
            <programlisting role="php"><![CDATA[
Zend_Locale_Format::setOptions(array('locale' => 'en_US',
                                     'date_format' => 'dd.MMMM.YYYY'));
// グローバル設定の日付書式をオーバーライドします
$date = Zend_Locale_Format::getDate('2007-04-20',
                                    array('date_format' =>
                                              Zend_Locale_Format::STANDARD);

// 標準ロケールのグローバル設定
Zend_Locale_Format::setOptions(array('locale' => Zend_Locale_Format::STANDARD,
                                     'date_format' => 'dd.MMMM.YYYY'));
]]>
            </programlisting>
        </example>

    </sect2>


    <sect2 id="zend.locale.cache">

        <title><classname>Zend_Locale</classname> とそのサブクラスの高速化</title>

        <para>
            <classname>Zend_Locale</classname> およびそのサブクラスを高速化するには、
            <classname>Zend_Cache</classname> を使用します。<classname>Zend_Locale</classname>
            を使用している場合は、静的メソッド <classname>Zend_Locale::setCache($cache)</classname>
            を使用します。<classname>Zend_Locale_Format</classname> を高速化するには、
            オプション <code>cache</code> を
            <classname>Zend_Locale_Format::setOptions(array('cache' => $adapter));</classname>
            のように指定します。両方のクラスを使用している場合は <classname>Zend_Locale</classname>
            にのみキャッシュを設定します。そうしないと、
            後から設定したキャッシュがそれまでの内容を上書きしてしまうことになります。
            利便性を考慮して、静的メソッド
            <code>getCache()</code>、<code>hasCache()</code>、<code>clearCache()</code> および
            <code>removeCache()</code> も用意されています。
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->