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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.form.i18n">
    <title>Internationalization of Zend_Form</title>

    <para>
        Increasingly, developers need to tailor their content for multiple
        languages and regions. <classname>Zend_Form</classname> aims to make such a task trivial,
        and leverages functionality in both <link
            linkend="zend.translate">Zend_Translate</link> and <link
            linkend="zend.validate">Zend_Validate</link> to do so.
    </para>

    <para>
        By default, no internationalisation (I18n) is performed. To turn on I18n
        features in <classname>Zend_Form</classname>, you will need to instantiate a
        <classname>Zend_Translate</classname> object with an appropriate adapter, and
        attach it to <classname>Zend_Form</classname> and/or <classname>Zend_Validate</classname>.
        See the <link linkend="zend.translate">Zend_Translate
            documentation</link> for more information on creating the translate
        object and translation files
    </para>

    <note>
        <title>Translation Can Be Turned Off Per Item</title>

        <para>
            You can disable translation for any form, element, display group, or
            sub form by calling its <methodname>setDisableTranslator($flag)</methodname>
            method or passing a <property>disableTranslator</property> option to the
            object. This can be useful when you want to selectively disable
            translation for individual elements or sets of elements.
        </para>
    </note>

    <sect2 id="zend.form.i18n.initialization">
        <title>Initializing I18n in Forms</title>

        <para>
            In order to initialize I18n in forms, you will need either a
            <classname>Zend_Translate</classname> object or a
            <classname>Zend_Translate_Adapter</classname> object, as detailed in the
            <classname>Zend_Translate</classname> documentation. Once you have a
            translation object, you have several options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Easiest:</emphasis> add it to the registry. All I18n
                    aware components of Zend Framework will autodiscover a translate
                    object that is in the registry under the 'Zend_Translate' key
                    and use it to perform translation and/or localization:
                </para>

                <programlisting language="php"><![CDATA[
// use the 'Zend_Translate' key; $translate is a Zend_Translate object:
Zend_Registry::set('Zend_Translate', $translate);
]]></programlisting>

                <para>
                    This will be picked up by <classname>Zend_Form</classname>,
                    <classname>Zend_Validate</classname>, and
                    <classname>Zend_View_Helper_Translate</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    If all you are worried about is translating validation error
                    messages, you can register the translation object with
                    <classname>Zend_Validate_Abstract</classname>:
                </para>

                <programlisting language="php"><![CDATA[
// Tell all validation classes to use a specific translate adapter:
Zend_Validate_Abstract::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Alternatively, you can attach to the <classname>Zend_Form</classname>
                    object as a global translator. This has the side effect of also
                    translating validation error messages:
                </para>

                <programlisting language="php"><![CDATA[
// Tell all form classes to use a specific translate adapter, as well
// as use this adapter to translate validation error messages:
Zend_Form::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Finally, you can attach a translator to a specific form instance
                    or to specific elements using their <methodname>setTranslator()</methodname>
                    methods:
                </para>

                <programlisting language="php"><![CDATA[
// Tell *this* form instance to use a specific translate adapter; it
// will also be used to translate validation error messages for all
// elements:
$form->setTranslator($translate);

// Tell *this* element to use a specific translate adapter; it will
// also be used to translate validation error messages for this
// particular element:
$element->setTranslator($translate);
]]></programlisting>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.i18n.standard">
        <title>Standard I18n Targets</title>

        <para>
            Now that you've attached a translation object to, what exactly can
            you translate by default?
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Validation error messages.</emphasis> Validation
                    error messages may be translated. To do so, use the various
                    error code constants from the <classname>Zend_Validate</classname>
                    validation classes as the message IDs. For more information
                    on these codes, see the <link
                        linkend="zend.validate">Zend_Validate</link>
                    documentation.
                </para>

                <para>
                    Alternately, as of 1.6.0, you may provide translation
                    strings using the actual error messages as message
                    identifiers. This is the preferred use case for 1.6.0 and
                    up, as we will be deprecating translation of message keys in
                    future releases.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Labels.</emphasis> Element labels will be
                    translated, if a translation exists.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Fieldset Legends.</emphasis> Display groups and
                    sub forms render in fieldsets by default. The Fieldset
                    decorator attempts to translate the legend before rendering
                    the fieldset.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Form and Element Descriptions.</emphasis> All form
                    types (element, form, display group, sub form) allow
                    specifying an optional item description. The Description
                    decorator can be used to render this, and by default will
                    take the value and attempt to translate it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Multi-option Values.</emphasis> for the various
                    items inheriting from <classname>Zend_Form_Element_Multi</classname>
                    (including the MultiCheckbox, Multiselect, and Radio
                    elements), the option values (not keys) will be translated
                    if a translation is available; this means that the option
                    labels presented to the user will be translated.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Submit and Button Labels.</emphasis> The various
                    Submit and Button elements (Button, Submit, and Reset) will
                    translate the label displayed to the user.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->