documentation/manual/en/module_specs/Zend_View-Helpers-Translate.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.translate">
   4     <title>Translate Helper</title>
   5
   6     <para>
   7         Often web sites are available in several languages. To translate the
   8         content of a site you should simply use <link
   9             linkend="zend.translate.introduction">Zend_Translate</link> and to
  10         integrate <classname>Zend_Translate</classname> within your view you should use
  11         the <emphasis>Translate</emphasis> View Helper.
  12     </para>
  13
  14     <para>
  15         In all following examples we are using the simple Array Translation
  16         Adapter. Of course you can also use any instance of
  17         <classname>Zend_Translate</classname> and also any subclasses of
  18         <classname>Zend_Translate_Adapter</classname>. There are several ways to initiate
  19         the <emphasis>Translate</emphasis> View Helper:
  20     </para>
  21
  22     <itemizedlist>
  23         <listitem>
  24             <para>
  25                 Registered, through a previously registered instance in
  26                 <classname>Zend_Registry</classname>
  27             </para>
  28         </listitem>
  29
  30         <listitem>
  31             <para>
  32                 Afterwards, through the fluent interface
  33             </para>
  34         </listitem>
  35
  36         <listitem>
  37             <para>
  38                 Directly, through initiating the class
  39             </para>
  40         </listitem>
  41     </itemizedlist>
  42
  43     <para>
  44         A registered instance of <classname>Zend_Translate</classname> is the preferred
  45         usage for this helper. You can also select the locale to be used simply
  46         before you add the adapter to the registry.
  47     </para>
  48
  49     <note>
  50         <para>
  51             We are speaking of locales instead of languages because a language
  52             also may contain a region. For example English is spoken in
  53             different dialects. There may be a translation for British and one
  54             for American English. Therefore, we say "locale" instead of
  55             "language."
  56         </para>
  57     </note>
  58
  59     <example id="zend.view.helpers.initial.translate.registered">
  60         <title>Registered instance</title>
  61
  62         <para>
  63             To use a registered instance just create an instance of
  64             <classname>Zend_Translate</classname> or <classname>Zend_Translate_Adapter</classname>
  65             and register it within <classname>Zend_Registry</classname> using
  66             <classname>Zend_Translate</classname> as its key.
  67         </para>
  68
  69         <programlisting language="php"><![CDATA[
  70 // our example adapter
  71 $adapter = new Zend_Translate(
  72     array(
  73         'adapter' => 'array',
  74         'content' => array('simple' => 'einfach'),
  75         'locale'  => 'de'
  76     )
  77 );
  78 Zend_Registry::set('Zend_Translate', $adapter);
  79
  80 // within your view
  81 echo $this->translate('simple');
  82 // this returns 'einfach'
  83 ]]></programlisting>
  84     </example>
  85
  86     <para>
  87         If you are more familiar with the fluent interface, then you can also
  88         create an instance within your view and initiate the helper afterwards.
  89     </para>
  90
  91     <example id="zend.view.helpers.initial.translate.afterwards">
  92         <title>Within the view</title>
  93
  94         <para>
  95             To use the fluent interface, create an instance of
  96             <classname>Zend_Translate</classname> or <classname>Zend_Translate_Adapter</classname>,
  97             call the helper without a parameter, and call the
  98             <methodname>setTranslator()</methodname> method.
  99         </para>
 100
 101         <programlisting language="php"><![CDATA[
 102 // within your view
 103 $adapter = new Zend_Translate(
 104     array(
 105         'adapter' => 'array',
 106         'content' => array('simple' => 'einfach'),
 107         'locale'  => 'de'
 108     )
 109 );
 110 $this->translate()->setTranslator($adapter)->translate('simple');
 111 // this returns 'einfach'
 112 ]]></programlisting>
 113     </example>
 114
 115     <para>
 116         If you are using the helper without <classname>Zend_View</classname> then you can
 117         also use it directly.
 118     </para>
 119
 120     <example id="zend.view.helpers.initial.translate.directly">
 121         <title>Direct usage</title>
 122
 123         <programlisting language="php"><![CDATA[
 124 // our example adapter
 125 $adapter = new Zend_Translate(
 126     array(
 127         'adapter' => 'array',
 128         'content' => array('simple' => 'einfach'),
 129         'locale'  => 'de'
 130     )
 131 );
 132
 133 // initiate the adapter
 134 $translate = new Zend_View_Helper_Translate($adapter);
 135 print $translate->translate('simple'); // this returns 'einfach'
 136 ]]></programlisting>
 137
 138         <para>
 139             You would use this way if you are not working with
 140             <classname>Zend_View</classname> and need to create translated output.
 141         </para>
 142     </example>
 143
 144     <para>
 145         As already seen, the <methodname>translate()</methodname> method is used to return
 146         the translation. Just call it with the needed messageid of your
 147         translation adapter. But it can also replace parameters within the
 148         translation string. Therefore, it accepts variable parameters in two ways:
 149         either as a list of parameters, or as an array of parameters. As examples:
 150     </para>
 151
 152     <example id="zend.view.helpers.initial.translate.parameter">
 153         <title>Single parameter</title>
 154
 155         <para>
 156             To use a single parameter just add it to the method.
 157         </para>
 158
 159         <programlisting language="php"><![CDATA[
 160 // within your view
 161 $date = "Monday";
 162 $this->translate("Today is %1\$s", $date);
 163 // could return 'Heute ist Monday'
 164 ]]></programlisting>
 165     </example>
 166
 167     <note>
 168         <para>
 169             Keep in mind that if you are using parameters which are also text,
 170             you may also need to translate these parameters.
 171         </para>
 172     </note>
 173
 174     <example id="zend.view.helpers.initial.translate.parameterlist">
 175         <title>List of parameters</title>
 176
 177         <para>
 178             Or use a list of parameters and add it to the method.
 179         </para>
 180
 181         <programlisting language="php"><![CDATA[
 182 // within your view
 183 $date = "Monday";
 184 $month = "April";
 185 $time = "11:20:55";
 186 $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s",
 187                  $date,
 188                  $month,
 189                  $time);
 190 // Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
 191 ]]></programlisting>
 192     </example>
 193
 194     <example id="zend.view.helpers.initial.translate.parameterarray">
 195         <title>Array of parameters</title>
 196
 197         <para>
 198             Or use an array of parameters and add it to the method.
 199         </para>
 200
 201         <programlisting language="php"><![CDATA[
 202 // within your view
 203 $date = array("Monday", "April", "11:20:55");
 204 $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
 205 // Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
 206 ]]></programlisting>
 207     </example>
 208
 209     <para>
 210         Sometimes it is necessary to change the locale of the translation. This
 211         can be done either dynamically per translation or statically for all
 212         following translations. And you can use it with both a parameter list
 213         and an array of parameters. In both cases the locale must be given as
 214         the last single parameter.
 215     </para>
 216
 217     <example id="zend.view.helpers.initial.translate.dynamic">
 218         <title>Change locale dynamically</title>
 219
 220         <programlisting language="php"><![CDATA[
 221 // within your view
 222 $date = array("Monday", "April", "11:20:55");
 223 $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date, 'it');
 224 ]]></programlisting>
 225     </example>
 226
 227     <para>
 228         This example returns the Italian translation for the messageid. But it
 229         will only be used once. The next translation will use the locale from
 230         the adapter. Normally you will set the desired locale within the
 231         translation adapter before you add it to the registry. But you can also
 232         set the locale from within the helper:
 233     </para>
 234
 235     <example id="zend.view.helpers.initial.translate.static">
 236         <title>Change locale statically</title>
 237
 238         <programlisting language="php"><![CDATA[
 239 // within your view
 240 $date = array("Monday", "April", "11:20:55");
 241 $this->translate()->setLocale('it');
 242 $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
 243 ]]></programlisting>
 244     </example>
 245
 246     <para>
 247         The above example sets <emphasis>'it'</emphasis> as the new default locale which
 248         will be used for all further translations.
 249     </para>
 250
 251     <para>
 252         Of course there is also a <methodname>getLocale()</methodname> method to get the
 253         currently set locale.
 254     </para>
 255
 256     <example id="zend.view.helpers.initial.translate.getlocale">
 257         <title>Get the currently set locale</title>
 258
 259         <programlisting language="php"><![CDATA[
 260 // within your view
 261 $date = array("Monday", "April", "11:20:55");
 262
 263 // returns 'de' as set default locale from our above examples
 264 $this->translate()->getLocale();
 265
 266 $this->translate()->setLocale('it');
 267 $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
 268
 269 // returns 'it' as new set default locale
 270 $this->translate()->getLocale();
 271 ]]></programlisting>
 272     </example>
 273 </sect3>
 274 <!--
 275 vim:se ts=4 sw=4 et:
 276 -->