repo_zf1/documentation/manual/ja/module_specs/Zend_Form-I18n.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.form.i18n">
    <title>Zend_Form の国際化</title>

    <para>
        作成したコンテンツを複数の言語や地域に対応させるという作業は、
        日増しに重要になってきています。
        <classname>Zend_Form</classname> はそんな作業も簡単にできるように作られており、
        <link
            linkend="zend.translate">Zend_Translate</link> と <link
            linkend="zend.validate">Zend_Validate</link>
        の機能を使うことで国際化を実現できます。
    </para>

    <para>
        デフォルトでは、国際化 (I18n) は行われません。
        i18n 機能を <classname>Zend_Form</classname> で使うには、まず適切なアダプタを指定して
        <classname>Zend_Translate</classname> のインスタンスを作成し、それを
        <classname>Zend_Form</classname> や <classname>Zend_Validate</classname>
        にアタッチしなければなりません。翻訳オブジェクトや翻訳ファイルの作成方法についての詳細は
        <link linkend="zend.translate">Zend_Translate
        のドキュメント</link> を参照ください。
    </para>

    <note>
        <title>項目単位での翻訳の無効化</title>

        <para>
            個々のフォームや要素、表示グループ、サブフォームなどの単位で翻訳を無効にするには、
            <methodname>setDisableTranslator($flag)</methodname> メソッドをコールするか
            あるいはそのオブジェクトにオプション <property>disableTranslator</property>
            を渡します。これは、特定の要素 (あるいは要素群)
            についてだけ翻訳を無効にしたい場合に有用です。
        </para>
    </note>

    <sect2 id="zend.form.i18n.initialization">
        <title>フォームでの I18n 機能の初期化</title>

        <para>
            フォームの I18n 機能を初期化するには
            <classname>Zend_Translate</classname> オブジェクトあるいは
            <classname>Zend_Translate_Adapter</classname> オブジェクトが必要です。詳細は
            <classname>Zend_Translate</classname> のドキュメントを参照ください。
            翻訳オブジェクトを作成したら、その後の手順にはいくつかの方法があります。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>最も簡単な方法:</emphasis>
                    レジストリに登録します。Zend Framework の I18n
                    対応コンポーネントはすべて、レジストリの 'Zend_Translate'
                    キーに登録されている翻訳オブジェクトを自動取得して翻訳や地域化を行います。
                </para>

                <programlisting language="php"><![CDATA[
// 'Zend_Translate' キーを使用します。$translate は Zend_Translate オブジェクトです
Zend_Registry::set('Zend_Translate', $translate);
]]></programlisting>

                <para>
                    これは、<classname>Zend_Form</classname> や
                    <classname>Zend_Validate</classname> そして
                    <classname>Zend_View_Helper_Translate</classname> が使用します。
                </para>
            </listitem>

            <listitem>
                <para>
                    検証エラーのメッセージだけを翻訳したいのなら、
                    翻訳オブジェクトを <classname>Zend_Validate_Abstract</classname> に登録することもできます。
                </para>

                <programlisting language="php"><![CDATA[
// すべてのバリデーションクラスに、指定した翻訳アダプタを使用させます
Zend_Validate_Abstract::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    あるいは、<classname>Zend_Form</classname>
                    オブジェクトにアタッチしてグローバルに使用することもできます。
                    その副作用として、検証エラーメッセージも翻訳されます。
                </para>

                <programlisting language="php"><![CDATA[
// すべてのフォームクラスで特定の翻訳アダプタを使用させます。
// このアダプタは、検証エラーメッセージの翻訳にも用いられます。
Zend_Form::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    最後に、特定のフォームや要素のインスタンスに
                    翻訳オブジェクトをアタッチすることもできます。
                    その場合は <methodname>setTranslator()</methodname>
                    メソッドを使用します。
                </para>

                <programlisting language="php"><![CDATA[
// 「この」フォームのインスタンスで特定の翻訳アダプタを使用させます。
// このアダプタは、すべての要素の検証エラーメッセージの翻訳にも用いられます。
$form->setTranslator($translate);

// 「この」要素のインスタンスで特定の翻訳アダプタを使用させます。
// このアダプタは、この要素の検証エラーメッセージの翻訳にも用いられます。
$element->setTranslator($translate);
]]></programlisting>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.i18n.standard">
        <title>標準的な I18N の対象</title>

        <para>
            これで翻訳オブジェクトがアタッチできました。
            デフォルトでは、いったい何が翻訳の対象となるのでしょうか?
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>検証エラーメッセージ。</emphasis>
                    検証エラーメッセージを翻訳させることができます。
                    そのためには、<classname>Zend_Validate</classname>
                    のバリデーションクラスのエラーコード定数をメッセージ ID として使用します。
                    エラーコードについての詳細は <link
                        linkend="zend.validate">Zend_Validate</link>
                    のドキュメントを参照ください。
                </para>

                <para>
                    1.6.0 以降では、実際のエラーメッセージをメッセージ ID
                    とする翻訳文字列を提供することができます。
                    1.6.0 以降ではこの方法が推奨となります。
                    メッセージキーによる翻訳は将来のバージョンで廃止予定です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ラベル。</emphasis>
                    要素のラベルも、翻訳が存在すれば翻訳されます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>フィールドセットの説明 (legend)。</emphasis>
                    表示グループやサブフォームは、デフォルトでは fieldset
                    としてレンダリングされます。Fieldset デコレータは、
                    レンダリングの前に legend の翻訳を試みます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>フォームや要素の説明。</emphasis>
                    すべての型 (要素、フォーム、表示グループ、サブフォーム)
                    で、オプションとしてその項目の説明を指定することができます。
                    Description デコレータを用いて、これをレンダリングします。
                    その際、デフォルトでこの値の翻訳を試みます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>選択肢の値。</emphasis>
                    <classname>Zend_Form_Element_Multi</classname> を継承した項目
                    (MultiCheckbox、Multiselect および Radio 要素)
                    で、もし翻訳がある場合に選択肢の値 (キーではありません)
                    が翻訳の対象となります。つまり、
                    ユーザ向けに表示される選択肢のラベルが翻訳されるということです。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>ボタンのラベル。</emphasis>
                    ボタン系の要素 (Button、Submit および Reset)
                    で、ユーザ向けに表示されるラベルが翻訳されます。
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->