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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.form.i18n">
   4     <title>Internationalization of Zend_Form</title>
   5
   6     <para>
   7         Increasingly, developers need to tailor their content for multiple
   8         languages and regions. <classname>Zend_Form</classname> aims to make such a task trivial,
   9         and leverages functionality in both <link
  10             linkend="zend.translate">Zend_Translate</link> and <link
  11             linkend="zend.validate">Zend_Validate</link> to do so.
  12     </para>
  13
  14     <para>
  15         By default, no internationalisation (I18n) is performed. To turn on I18n
  16         features in <classname>Zend_Form</classname>, you will need to instantiate a
  17         <classname>Zend_Translate</classname> object with an appropriate adapter, and
  18         attach it to <classname>Zend_Form</classname> and/or <classname>Zend_Validate</classname>.
  19         See the <link linkend="zend.translate">Zend_Translate
  20             documentation</link> for more information on creating the translate
  21         object and translation files
  22     </para>
  23
  24     <note>
  25         <title>Translation Can Be Turned Off Per Item</title>
  26
  27         <para>
  28             You can disable translation for any form, element, display group, or
  29             sub form by calling its <methodname>setDisableTranslator($flag)</methodname>
  30             method or passing a <property>disableTranslator</property> option to the
  31             object. This can be useful when you want to selectively disable
  32             translation for individual elements or sets of elements.
  33         </para>
  34     </note>
  35
  36     <sect2 id="zend.form.i18n.initialization">
  37         <title>Initializing I18n in Forms</title>
  38
  39         <para>
  40             In order to initialize I18n in forms, you will need either a
  41             <classname>Zend_Translate</classname> object or a
  42             <classname>Zend_Translate_Adapter</classname> object, as detailed in the
  43             <classname>Zend_Translate</classname> documentation. Once you have a
  44             translation object, you have several options:
  45         </para>
  46
  47         <itemizedlist>
  48             <listitem>
  49                 <para>
  50                     <emphasis>Easiest:</emphasis> add it to the registry. All I18n
  51                     aware components of Zend Framework will autodiscover a translate
  52                     object that is in the registry under the 'Zend_Translate' key
  53                     and use it to perform translation and/or localization:
  54                 </para>
  55
  56                 <programlisting language="php"><![CDATA[
  57 // use the 'Zend_Translate' key; $translate is a Zend_Translate object:
  58 Zend_Registry::set('Zend_Translate', $translate);
  59 ]]></programlisting>
  60
  61                 <para>
  62                     This will be picked up by <classname>Zend_Form</classname>,
  63                     <classname>Zend_Validate</classname>, and
  64                     <classname>Zend_View_Helper_Translate</classname>.
  65                 </para>
  66             </listitem>
  67
  68             <listitem>
  69                 <para>
  70                     If all you are worried about is translating validation error
  71                     messages, you can register the translation object with
  72                     <classname>Zend_Validate_Abstract</classname>:
  73                 </para>
  74
  75                 <programlisting language="php"><![CDATA[
  76 // Tell all validation classes to use a specific translate adapter:
  77 Zend_Validate_Abstract::setDefaultTranslator($translate);
  78 ]]></programlisting>
  79             </listitem>
  80
  81             <listitem>
  82                 <para>
  83                     Alternatively, you can attach to the <classname>Zend_Form</classname>
  84                     object as a global translator. This has the side effect of also
  85                     translating validation error messages:
  86                 </para>
  87
  88                 <programlisting language="php"><![CDATA[
  89 // Tell all form classes to use a specific translate adapter, as well
  90 // as use this adapter to translate validation error messages:
  91 Zend_Form::setDefaultTranslator($translate);
  92 ]]></programlisting>
  93             </listitem>
  94
  95             <listitem>
  96                 <para>
  97                     Finally, you can attach a translator to a specific form instance
  98                     or to specific elements using their <methodname>setTranslator()</methodname>
  99                     methods:
 100                 </para>
 101
 102                 <programlisting language="php"><![CDATA[
 103 // Tell *this* form instance to use a specific translate adapter; it
 104 // will also be used to translate validation error messages for all
 105 // elements:
 106 $form->setTranslator($translate);
 107
 108 // Tell *this* element to use a specific translate adapter; it will
 109 // also be used to translate validation error messages for this
 110 // particular element:
 111 $element->setTranslator($translate);
 112 ]]></programlisting>
 113             </listitem>
 114         </itemizedlist>
 115     </sect2>
 116
 117     <sect2 id="zend.form.i18n.standard">
 118         <title>Standard I18n Targets</title>
 119
 120         <para>
 121             Now that you've attached a translation object to, what exactly can
 122             you translate by default?
 123         </para>
 124
 125         <itemizedlist>
 126             <listitem>
 127                 <para>
 128                     <emphasis>Validation error messages.</emphasis> Validation
 129                     error messages may be translated. To do so, use the various
 130                     error code constants from the <classname>Zend_Validate</classname>
 131                     validation classes as the message IDs. For more information
 132                     on these codes, see the <link
 133                         linkend="zend.validate">Zend_Validate</link>
 134                     documentation.
 135                 </para>
 136
 137                 <para>
 138                     Alternately, as of 1.6.0, you may provide translation
 139                     strings using the actual error messages as message
 140                     identifiers. This is the preferred use case for 1.6.0 and
 141                     up, as we will be deprecating translation of message keys in
 142                     future releases.
 143                 </para>
 144             </listitem>
 145
 146             <listitem>
 147                 <para>
 148                     <emphasis>Labels.</emphasis> Element labels will be
 149                     translated, if a translation exists.
 150                 </para>
 151             </listitem>
 152
 153             <listitem>
 154                 <para>
 155                     <emphasis>Fieldset Legends.</emphasis> Display groups and
 156                     sub forms render in fieldsets by default. The Fieldset
 157                     decorator attempts to translate the legend before rendering
 158                     the fieldset.
 159                 </para>
 160             </listitem>
 161
 162             <listitem>
 163                 <para>
 164                     <emphasis>Form and Element Descriptions.</emphasis> All form
 165                     types (element, form, display group, sub form) allow
 166                     specifying an optional item description. The Description
 167                     decorator can be used to render this, and by default will
 168                     take the value and attempt to translate it.
 169                 </para>
 170             </listitem>
 171
 172             <listitem>
 173                 <para>
 174                     <emphasis>Multi-option Values.</emphasis> for the various
 175                     items inheriting from <classname>Zend_Form_Element_Multi</classname>
 176                     (including the MultiCheckbox, Multiselect, and Radio
 177                     elements), the option values (not keys) will be translated
 178                     if a translation is available; this means that the option
 179                     labels presented to the user will be translated.
 180                 </para>
 181             </listitem>
 182
 183             <listitem>
 184                 <para>
 185                     <emphasis>Submit and Button Labels.</emphasis> The various
 186                     Submit and Button elements (Button, Submit, and Reset) will
 187                     translate the label displayed to the user.
 188                 </para>
 189             </listitem>
 190         </itemizedlist>
 191     </sect2>
 192 </sect1>
 193 <!--
 194 vim:se ts=4 sw=4 tw=80 et:
 195 -->