|
|
@@ -5,55 +5,144 @@
|
|
|
|
|
|
<para>
|
|
|
<classname>Zend_Application_Resource_Locale</classname> can be used to
|
|
|
- set an (application-wide) locale to use in classes that use localization.
|
|
|
+ set an application-wide locale which is then used in all classes and components
|
|
|
+ which work with localization or internationalization.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- There are basically three uses of the Locale Resource Plugin.
|
|
|
- With one you don't specify any options for the Resource Plugin.
|
|
|
- By doing so, <classname>Zend_Locale</classname> tries to determine
|
|
|
- what locale to use, and that's it. Doing so is not adivsed. There are
|
|
|
- cases in which <classname>Zend_Locale</classname> cannot detect the
|
|
|
- locale of the user, resulting in an exception. For more info on how
|
|
|
- locales are detected, please see the chapter on <link
|
|
|
- linkend="zend.locale.selection.automatic">automatic locale detection</link>.
|
|
|
+ There are basically three usecases for the Locale Resource Plugin. Each of them
|
|
|
+ should be used depending on the applications need.
|
|
|
</para>
|
|
|
-
|
|
|
- <example id="zend.application.available-resources.locale.configExampleDetectAndFallback">
|
|
|
- <title>Autodetect locale as well as setting a fallback</title>
|
|
|
+
|
|
|
+ <sect3 id="zend.application.available-resources.locale.auto">
|
|
|
+ <title>Autodetect the locale to use</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Without specifying any options for
|
|
|
+ <classname>Zend_Application_Resource_Locale</classname>,
|
|
|
+ <classname>Zend_Locale</classname> will detect the locale, which your application will
|
|
|
+ use, automatically.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ This detection works because your client sends the wished language within his
|
|
|
+ <acronym>HTTP</acronym> request. Normally the clients browser sends the languages he
|
|
|
+ wants to see, and <classname>Zend_Locale</classname> uses this information for
|
|
|
+ detection.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ But there are 2 problems with this approach:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ The browser could be setup to send no language
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ The user could have manually set a locale which does not exist
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ In both cases <classname>Zend_Locale</classname> will fallback to other mechanism to
|
|
|
+ detect the locale:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ When a locale has been set which does not exist,
|
|
|
+ <classname>Zend_Locale</classname> tries to downgrade this string.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ When, for example, <emphasis>en_ZZ</emphasis> is set it will automatically
|
|
|
+ be degraded to <emphasis>en</emphasis>. In this case <emphasis>en</emphasis>
|
|
|
+ will be used as locale for your application.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ When the locale could also not be detected by downgrading, the locale of your
|
|
|
+ environment (web server) will be used. Most available environments from
|
|
|
+ Web Hosters use <emphasis>en</emphasis> as locale.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ When the systems locale could not be detected <classname>Zend_Locale</classname>
|
|
|
+ will use it's default locale, which is set to <emphasis>en</emphasis> per
|
|
|
+ default.
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ For more informations about locale detection take a look into <link
|
|
|
+ linkend="zend.locale.selection.automatic">this chapter on Zend_Locale's automatic
|
|
|
+ detection</link>.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.application.available-resources.locale.fallback">
|
|
|
+ <title>Autodetect the locale and adding a own fallback</title>
|
|
|
|
|
|
<para>
|
|
|
- Another possibility is to automatically detect the locale to use,
|
|
|
- but, when none can be found, still fall back to the pre-configured
|
|
|
- locale. This is advised for any application that needs to be localized.
|
|
|
+ The above autodetection could lead to problems when the locale could not be detected and
|
|
|
+ you want to have another default locale than <emphasis>en</emphasis>. To prevent this,
|
|
|
+ <classname>Zend_Application_Resource_Locale</classname> allows you to set a own locale
|
|
|
+ which will be used in the case that the locale could not be detected.
|
|
|
</para>
|
|
|
|
|
|
- <programlisting language="ini"><![CDATA[
|
|
|
+ <example id="zend.application.available-resources.locale.configExampleDetectAndFallback">
|
|
|
+ <title>Autodetect locale and setting a fallback</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The following snippet shows how to set a own default locale which will be used when
|
|
|
+ the client does not send a locale himself.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="ini"><![CDATA[
|
|
|
; Try to determine automatically first,
|
|
|
; if unsuccessful, use nl_NL as fallback.
|
|
|
resources.locale.default = "nl_NL"
|
|
|
-resources.locale.force = false
|
|
|
]]></programlisting>
|
|
|
+ </example>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="zend.application.available-resources.locale.forcing">
|
|
|
+ <title>Forcing a specific locale to use</title>
|
|
|
|
|
|
<para>
|
|
|
- Please note that the last line could be left out, since the
|
|
|
- force-directive defaults to false.
|
|
|
+ Sometimes it is useful to define a single locale which has to be used. This can be done
|
|
|
+ by using the <property>force</property> option.
|
|
|
</para>
|
|
|
- </example>
|
|
|
-
|
|
|
- <example id="zend.application.available-resources.locale.configExampleFallbackOnly">
|
|
|
- <title>Setting a locale only</title>
|
|
|
|
|
|
<para>
|
|
|
- The last option is to only set a preconfigured locale which is used
|
|
|
- in all cases. This comes in handy when you want the same locale
|
|
|
- throughout your entire application.
|
|
|
+ In this case this single locale will be used and the the automatic detection is turned
|
|
|
+ off.
|
|
|
</para>
|
|
|
|
|
|
- <programlisting language="ini"><![CDATA[
|
|
|
+ <example id="zend.application.available-resources.locale.configExampleFallbackOnly">
|
|
|
+ <title>Defining a single locale to use</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The following snippet shows how to set a single locale for your entire application.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="ini"><![CDATA[
|
|
|
; No matter what, the nl_NL locale will be used.
|
|
|
resources.locale.default = "nl_NL"
|
|
|
resources.locale.force = true
|
|
|
]]></programlisting>
|
|
|
- </example>
|
|
|
+ </example>
|
|
|
+ </sect3>
|
|
|
</sect2>
|
thomas