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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.application.available-resources.locale">
    <title>Zend_Application_Resource_Locale</title>

    <para>
        <classname>Zend_Application_Resource_Locale</classname> can be used to
        set an application-wide locale which is then used in all classes and components
        which work with localization or internationalization. By default the locale is
        saved in a <classname>Zend_Registry</classname> entry with key
        '<property>Zend_Locale</property>'.
    </para>

    <para>
        There are basically three usecases for the Locale Resource Plugin. Each of them
        should be used depending on the applications need.
    </para>

    <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>
            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>

        <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"
]]></programlisting>
        </example>
    </sect3>

    <sect3 id="zend.application.available-resources.locale.forcing">
        <title>Forcing a specific locale to use</title>

        <para>
            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>

        <para>
            In this case this single locale will be used and the automatic detection is turned
            off.
        </para>

        <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>
    </sect3>

    <sect3 id="zend.application.available-resources.locale.cache">
        <title>Configure cache template</title>

        <para>
            When you have set no cache, <classname>Zend_Locale</classname> will set itself a cache
            with the file backend by default. But if you want to choose the backend or others
            options, you can use the name of a cache template or an instance of
            <classname>Zend_Cache_Core</classname>.
            For more informations look into <xref linkend="zend.locale.cache" />.
        </para>

        <example id="zend.application.available-resources.locale.configExampleCache">
            <title>Defining a cache template to use</title>

            <programlisting language="ini"><![CDATA[
; Optionally you can also the cache template to use for caching:
resources.locale.cache = "locale"
]]></programlisting>
        </example>
    </sect3>
</sect2>