documentation/manual/en/module_specs/Zend_Application-AvailableResources-Locale.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.application.available-resources.locale">
   4     <title>Zend_Application_Resource_Locale</title>
   5
   6     <para>
   7         <classname>Zend_Application_Resource_Locale</classname> can be used to
   8         set an application-wide locale which is then used in all classes and components
   9         which work with localization or internationalization.
  10     </para>
  11
  12     <para>
  13         There are basically three usecases for the Locale Resource Plugin. Each of them
  14         should be used depending on the applications need.
  15     </para>
  16
  17     <sect3 id="zend.application.available-resources.locale.auto">
  18         <title>Autodetect the locale to use</title>
  19
  20         <para>
  21             Without specifying any options for
  22             <classname>Zend_Application_Resource_Locale</classname>,
  23             <classname>Zend_Locale</classname> will detect the locale, which your application will
  24             use, automatically.
  25         </para>
  26
  27         <para>
  28             This detection works because your client sends the wished language within his
  29             <acronym>HTTP</acronym> request. Normally the clients browser sends the languages he
  30             wants to see, and <classname>Zend_Locale</classname> uses this information for
  31             detection.
  32         </para>
  33
  34         <para>
  35             But there are 2 problems with this approach:
  36         </para>
  37
  38         <itemizedlist>
  39             <listitem>
  40                 <para>
  41                     The browser could be setup to send no language
  42                 </para>
  43             </listitem>
  44
  45             <listitem>
  46                 <para>
  47                     The user could have manually set a locale which does not exist
  48                 </para>
  49             </listitem>
  50         </itemizedlist>
  51
  52         <para>
  53             In both cases <classname>Zend_Locale</classname> will fallback to other mechanism to
  54             detect the locale:
  55         </para>
  56
  57         <itemizedlist>
  58             <listitem>
  59                 <para>
  60                     When a locale has been set which does not exist,
  61                     <classname>Zend_Locale</classname> tries to downgrade this string.
  62                 </para>
  63
  64                 <para>
  65                     When, for example, <emphasis>en_ZZ</emphasis> is set it will automatically
  66                     be degraded to <emphasis>en</emphasis>. In this case <emphasis>en</emphasis>
  67                     will be used as locale for your application.
  68                 </para>
  69             </listitem>
  70
  71             <listitem>
  72                 <para>
  73                     When the locale could also not be detected by downgrading, the locale of your
  74                     environment (web server) will be used. Most available environments from
  75                     Web Hosters use <emphasis>en</emphasis> as locale.
  76                 </para>
  77             </listitem>
  78
  79             <listitem>
  80                 <para>
  81                     When the systems locale could not be detected <classname>Zend_Locale</classname>
  82                     will use it's default locale, which is set to <emphasis>en</emphasis> per
  83                     default.
  84                 </para>
  85             </listitem>
  86         </itemizedlist>
  87
  88         <para>
  89             For more informations about locale detection take a look into <link
  90                 linkend="zend.locale.selection.automatic">this chapter on Zend_Locale's automatic
  91                 detection</link>.
  92         </para>
  93     </sect3>
  94
  95     <sect3 id="zend.application.available-resources.locale.fallback">
  96         <title>Autodetect the locale and adding a own fallback</title>
  97
  98         <para>
  99             The above autodetection could lead to problems when the locale could not be detected and
 100             you want to have another default locale than <emphasis>en</emphasis>. To prevent this,
 101             <classname>Zend_Application_Resource_Locale</classname> allows you to set a own locale
 102             which will be used in the case that the locale could not be detected.
 103         </para>
 104
 105         <example id="zend.application.available-resources.locale.configExampleDetectAndFallback">
 106             <title>Autodetect locale and setting a fallback</title>
 107
 108             <para>
 109                 The following snippet shows how to set a own default locale which will be used when
 110                 the client does not send a locale himself.
 111             </para>
 112
 113             <programlisting language="ini"><![CDATA[
 114 ; Try to determine automatically first,
 115 ; if unsuccessful, use nl_NL as fallback.
 116 resources.locale.default = "nl_NL"
 117 ]]></programlisting>
 118         </example>
 119     </sect3>
 120
 121     <sect3 id="zend.application.available-resources.locale.forcing">
 122         <title>Forcing a specific locale to use</title>
 123
 124         <para>
 125             Sometimes it is useful to define a single locale which has to be used. This can be done
 126             by using the <property>force</property> option.
 127         </para>
 128
 129         <para>
 130             In this case this single locale will be used and the automatic detection is turned
 131             off.
 132         </para>
 133
 134         <example id="zend.application.available-resources.locale.configExampleFallbackOnly">
 135             <title>Defining a single locale to use</title>
 136
 137             <para>
 138                 The following snippet shows how to set a single locale for your entire application.
 139             </para>
 140
 141             <programlisting language="ini"><![CDATA[
 142 ; No matter what, the nl_NL locale will be used.
 143 resources.locale.default = "nl_NL"
 144 resources.locale.force = true
 145 ]]></programlisting>
 146         </example>
 147     </sect3>
 148 </sect2>