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

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

    <para>
        De plus en plus de développeurs ont besoin de fournir des applications multilingues.
        <classname>Zend_Form</classname> propose des moyens simples dans ce but, et gère cette
        responsabilité en tandem avec <link linkend="zend.translate">Zend_Translate</link> et <link
        linkend="zend.validate">Zend_Validate</link>.
    </para>

    <para>
        Par défaut, aucune internationalisation (i18n) n'est effectuée. Pour l'activer dans
        <classname>Zend_Form</classname>, vous devrez instancier un objet
        <classname>Zend_Translate</classname> avec un adaptateur et l'attacher à
        <classname>Zend_Form</classname> et/ou <classname>Zend_Validate</classname>. Voyez la <link
        linkend="zend.translate">documentation de Zend_Translate</link> pour plus d'informations sur
        la création de son objet et de ses adaptateurs.
    </para>

    <note>
        <title>L'i18n peut être désactivée par objet</title>

        <para>
            Vous pouvez désactiver la traduction pour tout formulaire, élément, groupe
            d'affichage ou sous-formulaire en appelant sa méthode
            <methodname>setDisableTranslator($flag)</methodname> ou en lui passant un paramètre
            <code>disableTranslator</code>. Ceci peut être utile pour désactiver l'i18n pour des
            éléments de formulaires individuels, ou des groupes d'éléments par exemple.
        </para>
    </note>

    <sect2 id="zend.form.i18n.initialization">
        <title>Initialiser l'i18n dans les formulaires</title>

        <para>
            Pour activer les traductions dans vos formulaires, vous avez besoin soit d'un
            objet <classname>Zend_Translate</classname> complet, ou alors d'un objet
            <classname>Zend_Translate_Adapter</classname> , comme ceci est détaillé dans la
            documentation de <classname>Zend_Translate</classname>. Une fois un objet d'i18n en
            votre possession, plusieurs choix s'offrent à vous&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Le plus simple</emphasis>&#160;: ajoutez l'objet d'i18n dans le
                    registre. Tout composant utilisant l'i18n dans Zend Framework a la capacité de
                    découvrir de lui-même un objet de traduction si celui-ci est enregistré dans le
                    registre à la clé "Zend_Translate"&#160;:
                </para>

                <programlisting language="php"><![CDATA[
// utilisez la clé registre 'Zend_Translate' ;
// $translate est un objet Zend_Translate :
Zend_Registry::set('Zend_Translate', $translate);
]]></programlisting>

                <para>
                    Cet objet sera cherché par <classname>Zend_Form</classname>,
                    <classname>Zend_Validate</classname>, et
                    <classname>Zend_View_Helper_Translate</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Si tout ce qui vous importe est la traduction des messages d'erreurs, vous
                    pouvez ajouter l'objet de traduction à
                    <classname>Zend_Validate_Abstract</classname>&#160;:
                </para>

                <programlisting language="php"><![CDATA[
// Indique aux classes de validation d'utiliser
// un objet de traduction spécifique :
Zend_Validate_Abstract::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Autre manière de procéder; attacher un objet de traduction à
                    <classname>Zend_Form</classname> de manière générale. Ceci aura pour effet,
                    entres-autres, de gérer la traduction des messages d'erreur de la
                    validation&#160;:
                </para>

                <programlisting language="php"><![CDATA[
// Indique à toutes les classes de formulaire d'utiliser un objet de traduction
// Indique aussi aux validateurs d'utiliser ce même objet pour traduire
// les messages d'erreur :
Zend_Form::setDefaultTranslator($translate);
]]></programlisting>
            </listitem>

            <listitem>
                <para>
                    Enfin, il est possible d'attacher un objet de traduction à une instance du
                    formulaire, ou à un ou plusieurs de ses éléments, grâce à
                    <methodname>setTranslator()</methodname>&#160;:
                </para>

                <programlisting language="php"><![CDATA[
// Indique à *cette* instance de formulaire, d'utiliser un objet de
// traduction. L'objet de traduction sera aussi utilisé par tous les
// validateurs pour traduire les messages d'erreur :
$form->setTranslator($translate);

// Indique à *cette* instance d'élément de formulaire, d'utiliser
// un objet de traduction. L'objet de traduction sera aussi utilisé
// par tous les validateurs de *cet* élément spécifique :
$element->setTranslator($translate);
]]></programlisting>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.form.i18n.standard">
        <title>Cibles gérées par l'I18n</title>

        <para>
            Maintenant que vous avez attaché un objet de traduction, que pouvez vous faire
            avec&#160;?
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>Messages d'erreur des validateurs</emphasis>&#160;: les messages
                    d'erreurs des validateurs peuvent être traduits. Pour cela, utilisez les
                    identifiants des messages des validateurs (constantes de vos validateurs
                    <classname>Zend_Validate</classname>. Pour plus d'informations sur ces clés,
                    voyez la documentation de <link
                    linkend="zend.validate">Zend_Validate</link>.
                </para>

                <para>
                    Aussi, depuis la version 1.6.0, vous pouvez fournir des chaînes de
                    traduction en utilisant les messages d'erreur actuels comme identifiants. C'est
                    le comportement recommandé pour 1.6.0 ou supérieures, nous allons déprécier
                    l'utilisation des clés (constantes de classe) dans les prochaines
                    versions.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Labels</emphasis>&#160;: les labels des éléments seront traduits si
                    un objet de traduction et une chaîne de traduction existent.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Légende des Fieldset</emphasis>&#160;: les groupes d'éléments et les
                    sous-formulaires sont rendus dans des "fieldsets" par défaut. Le décorateur
                    FieldSet essaye de traduire la légende via l'objet de traduction.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Description des formulaires et éléments de
                    formulaire</emphasis>&#160;: tous les types relatifs au formulaire (éléments,
                    formulaires, groupes d'éléments ou sous-formulaires) permettent de spécifier
                    une description optionnelle. Le décorateur Description essaye de traduire la
                    description.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Valeurs de Multi-option</emphasis>&#160;: les éléments héritant de
                    <classname>Zend_Form_Element_Multi</classname>(MultiCheckbox, Multiselect, et
                    Radio) peuvent aussi traduire les valeurs (et non les clés) de leurs
                    options.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>Labels de Submit et Button</emphasis>&#160;: les boutons (éléments
                    Submit, Button et Reset) vont traduire le label affiché à l'utilisateur.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>