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

<!-- EN-Revision: 13843 -->
<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 <code>setDisableTranslator($flag)</code> 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 :</para>

        <itemizedlist>
            <listitem>
                <para><emphasis>Le plus simple :</emphasis> 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" :</para>

                <programlisting role="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> :</para>

                <programlisting role="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 :</para>

                <programlisting role="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 à <code>setTranslator()</code> :</para>

                <programlisting role="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 ?</para>

        <itemizedlist>
            <listitem>
                <para><emphasis>Messages d'erreur des validateurs :</emphasis> 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> 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> 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>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> 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> les boutons (éléments Submit, Button et Reset)
                vont traduire le label affiché à l'utilisateur.</para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>