repo_zf1/documentation/manual/en/module_specs/Zend_Locale-Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.locale.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_Locale</classname> is the Frameworks answer to the question, "How can the
        same application be used around the whole world?" Most people will say, "That's easy. Let's
        translate all our output to several languages." However, using simple translation tables to
        map phrases from one language to another is not sufficient. Different regions will have
        different conventions for first names, surnames, salutory titles, formatting of numbers,
        dates, times, currencies, etc.
    </para>

    <para>
        We need <ulink url="http://en.wikipedia.org/wiki/L10n">Localization</ulink> and
        complementary <ulink url="http://en.wikipedia.org/wiki/L10n">Internationalization</ulink>.
        Both are often abbreviated to <code>L10n</code> and <code>I18n</code>. Internationalization
        refers more to support for use of systems, regardless of special needs unique to groups of
        users related by language, region, number format conventions, financial conventions, time
        and date conventions, etc. Localization involves adding explicit support to systems for
        special needs of these unique groups, such as language translation, and support for local
        customs or conventions for communicating plurals, dates, times, currencies, names, symbols,
        sorting and ordering, etc. <code>L10n</code> and <code>I18n</code> compliment each other.
        Zend Framework provides support for these through a combination of components, including
        <classname>Zend_Locale</classname>, <classname>Zend_Date</classname>,
        <classname>Zend_Measure</classname>, <classname>Zend_Translate</classname>,
        <classname>Zend_Currency</classname>, and <classname>Zend_TimeSync</classname>.
    </para>

    <tip>
        <title>Zend_Locale and setLocale()</title>

        <para>
            <ulink url="http://php.net/setlocale">PHP's documentation</ulink> states that
            <methodname>setlocale()</methodname> is not threadsave because it is maintained per
            process and not per thread. This means that, in multithreaded environments, you can have
            the problem that the locale changes while the script never has changed the locale
            itself. This can lead to unexpected behaviour when you use
            <methodname>setlocale()</methodname> in your scripts.
        </para>

        <para>
            When you are using <classname>Zend_Locale</classname> you will not have this
            limitations, because <classname>Zend_Locale</classname> is not related to or coupled
            with <acronym>PHP</acronym>'s <methodname>setlocale()</methodname>.
        </para>
    </tip>

    <sect2 id="zend.locale.whatislocalization">
        <title>What is Localization</title>

        <para>
            Localization means that an application (or homepage) can be used from different users
            which speak different languages. But as you already have expected Localization means
            more than only translating strings. It includes
        </para>

        <itemizedlist mark='opencircle'>
            <listitem>
                <para>
                    <classname>Zend_Locale</classname> - Backend support of locales available for
                    localization support within other Zend Framework components.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Translate</classname> - Translating of strings.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Date</classname> - Localization of dates, times.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Calendar</classname> - Localization of calendars (support for
                    non-Gregorian calendar systems)
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Currency</classname> - Localization of currencies.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Locale_Format</classname> - Parsing and generating localized
                    numbers.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Locale_Data</classname> - Retrieve localized standard strings
                    as country names, language names and <ulink
                        url="http://unicode.org/cldr/">more from the
                        <acronym>CLDR</acronym></ulink>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>TODO</code> - Localization of collations
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.locale.whatis">
        <title>What is a Locale?</title>

        <para>
            Each computer user makes use of Locales, even when they don't know it. Applications
            lacking localization support, normally have implicit support for one particular locale
            (the locale of the author). When a class or function makes use of localization, we say
            it is <code>locale-aware</code>. How does the code know which localization the user is
            expecting?
        </para>

        <para>
            A locale string or object identifying a supported locale gives
            <classname>Zend_Locale</classname> and its subclasses access to information about the
            language and region expected by the user. Correct formatting, normalization, and
            conversions are made based on this information.
        </para>
    </sect2>

    <sect2 id="zend.locale.representation">
        <title>How are Locales Represented?</title>

        <para>
            Locale identifiers consist of information about the user's language and
            preferred/primary geographic region (e.g. state or province of home or workplace). The
            locale identifier strings used in Zend Framework are internationally defined standard
            abbreviations of language and region, written as <code>language_REGION</code>. Both the
            language and region parts are abbreviated to alphabetic, <acronym>ASCII</acronym>
            characters.
        </para>

        <note>
            <para>
                Be aware that there exist not only locales with 2 characters as most people think.
                Also there are languages and regions which are not only abbreviated with 2
                characters. Therefor you should NOT strip the region and language yourself, but use
                <classname>Zend_Locale</classname> when you want to strip language or region from a
                locale string. Otherwise you could have unexpected behaviour within your code when
                you do this yourself.
            </para>
        </note>

        <para>
            A user from USA would expect the language <code>English</code> and the region
            <constant>USA</constant>, yielding the locale identifier "en_US". A user in Germany
            would expect the language <code>German</code> and the region <code>Germany</code>,
            yielding the locale identifier "de_DE". See the <ulink
                url="http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html">list
                of pre-defined locale and region combinations</ulink>, if you need to select a
            specific locale within Zend Framework.
        </para>

        <example id="zend.locale.representation.example-1">
            <title>Choosing a specific locale</title>

            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_DE'); // German language _ Germany
]]></programlisting>
        </example>

        <para>
            A German user in America might expect the language <code>German</code> and the region
            <constant>USA</constant>, but these non-standard mixes are not supported directly as
            recognized "locales". Instead, if an invalid combination is used, then it will
            automatically be truncated by dropping the region code. For example, "de_IS" would be
            truncated to "de", and "xh_RU" would be truncated to "xh", because neither of these
            combinations are valid. Additionally, if the base language code is not supported (e.g.
            "zz_US") or does not exist, then a default "root" locale will be used. The "root" locale
            has default definitions for internationally recognized representations of dates, times,
            numbers, currencies, etc. The truncation process depends on the requested information,
            since some combinations of language and region might be valid for one type of data (e.g.
            dates), but not for another (e.g. currency format).
        </para>

        <para>
            Beware of historical changes, as Zend Framework components do not know about or attempt
            to track the numerous timezone changes made over many years by many regions. For
            example, <ulink url="http://www.statoids.com/tus.html">we can see a historical
                list</ulink> showing dozens of changes made by governments to when and if a
            particular region observes Daylight Savings Time, and even which timezone a particular
            geographic area belongs. Thus, when performing date math, the math performed by Zend
            Framework components will not adjust for these changes, but instead will give the
            correct time for the timezone using current, modern rules for <acronym>DST</acronym> and
            timezone assignment for geographic regions.
        </para>
    </sect2>

    <sect2 id="zend.locale.selection">
        <title>Selecting the Right Locale</title>

        <para>
            For most situations, <code>new Zend_Locale()</code> will automatically select the
            correct locale, with preference given to information provided by the user's web browser.
            However, if <code>new Zend_Locale(Zend_Locale::ENVIRONMENT)</code> is used, then
            preference will be given to using the host server's environment configuration, as
            described below.
        </para>

        <example id="zend.locale.selection.example-1">
            <title>Automatically selecting a locale</title>

            <programlisting language="php"><![CDATA[
$locale  = new Zend_Locale();

// default behavior, same as above
$locale1 = new Zend_Locale(Zend_Locale::BROWSER);

// prefer settings on host server
$locale2 = new Zend_Locale(Zend_Locale::ENVIRONMENT);

// perfer framework app default settings
$locale3 = new Zend_Locale(Zend_Locale::FRAMEWORK);
]]></programlisting>
        </example>

        <para>
            The search algorithm used by <classname>Zend_Locale</classname> for automatic selection
            of a locale uses three sources of information:

            <orderedlist>
                <listitem>
                    <para>
                        const <constant>Zend_Locale::BROWSER</constant> - The user's Web browser
                        provides information with each request, which is published by
                        <acronym>PHP</acronym> in the global variable
                        <constant>HTTP_ACCEPT_LANGUAGE</constant>. if no matching locale can be
                        found, then preference is given to <constant>ENVIRONMENT</constant> and
                        lastly <constant>FRAMEWORK</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        const <constant>Zend_Locale::ENVIRONMENT</constant> - <acronym>PHP</acronym>
                        publishes the host server's locale via the <acronym>PHP</acronym> internal
                        function <methodname>setlocale()</methodname>. If no matching locale can be
                        found, then preference is given to <constant>FRAMEWORK</constant> and lastly
                        <constant>BROWSER</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        const <constant>Zend_Locale::FRAMEWORK</constant> - When Zend Framework has
                        a standardized way of specifying component defaults (planned, but not yet
                        available), then using this constant during instantiation will give
                        preference to choosing a locale based on these defaults. If no matching
                        locale can be found, then preference is given to
                        <constant>ENVIRONMENT</constant> and lastly <constant>BROWSER</constant>.
                    </para>
                </listitem>
            </orderedlist>
        </para>
    </sect2>

    <sect2 id="zend.locale.selection.automatic">
        <title>Usage of automatic Locales</title>

        <para>
            <classname>Zend_Locale</classname> provides three additionally locales. These locales do
            not belong to any language or region. They are "automatic" locales which means that they
            have the same effect as the method <methodname>getDefault()</methodname> but without the
            negative effects like creating an instance. These "automatic" locales can be used
            anywhere, where also a standard locale and also the definition of a locale, its string
            representation, can be used. This offers simplicity for situations like working with
            locales which are provided by a browser.
        </para>

        <para>
            There are three locales which have a slightly different behaviour:

            <orderedlist>
                <listitem>
                    <para>
                        <code>'browser'</code> - <classname>Zend_Locale</classname> should work with
                        the information which is provided by the user's Web browser. It is published
                        by <acronym>PHP</acronym> in the global variable
                        <constant>HTTP_ACCEPT_LANGUAGE</constant>.
                    </para>

                    <para>
                        If a user provides more than one locale within his browser,
                        <classname>Zend_Locale</classname> will use the first found locale. If the
                        user does not provide a locale or the script is being called from the
                        command line the automatic locale <code>'environment'</code> will
                        automatically be used and returned.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>'environment'</code> - <classname>Zend_Locale</classname> should work
                        with the information which is provided by the host server. It is published
                        by <acronym>PHP</acronym> via the internal function
                        <methodname>setlocale()</methodname>.
                    </para>

                    <para>
                        If a environment provides more than one locale,
                        <classname>Zend_Locale</classname> will use the first found locale. If the
                        host does not provide a locale the automatic locale <code>'browser'</code>
                        will automatically be used and returned.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>'auto'</code> - <classname>Zend_Locale</classname> should
                        automatically detect any locale which can be worked with. It will first
                        search for a users locale and then, if not successful, search for the host
                        locale.
                    </para>

                    <para>
                        If no locale can be detected, it will throw an exception and tell you that
                        the automatic detection has been failed.
                    </para>
                </listitem>
            </orderedlist>
        </para>

        <example id="zend.locale.selection.automatic.example-1">
            <title>Using automatic locales</title>

            <programlisting language="php"><![CDATA[
// without automatic detection
//$locale = new Zend_Locale(Zend_Locale::BROWSER);
//$date = new Zend_Date($locale);

// with automatic detection
$date = new Zend_Date('auto');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.defaultlocale">
        <title>Using a default Locale</title>

        <para>
            In some environments it is not possible to detect a locale automatically. You can expect
            this behaviour when you get an request from command line or the requesting browser has
            no language tag set and additionally your server has the default locale 'C' set or
            another proprietary locale.
        </para>

        <para>
            In such cases <classname>Zend_Locale</classname> will normally throw an exception with a
            message that the automatic detection of any locale was not successful. You have two
            options to handle such a situation. Either through setting a new locale per hand, or
            defining a default locale.
        </para>

        <example id="zend.locale.defaultlocale.example-1">
            <title>Handling locale exceptions</title>

            <programlisting language="php"><![CDATA[
// within the bootstrap file
try {
    $locale = new Zend_Locale('auto');
} catch (Zend_Locale_Exception $e) {
    $locale = new Zend_Locale('de');
}

// within your model/controller
$date = new Zend_Date($locale);
]]></programlisting>
        </example>

        <para>
            But this has one big negative effect. You will have to set your locale object within
            every class using <classname>Zend_Locale</classname>. This could become very unhandy if
            you are using multiple classes.
        </para>

        <para>
            Since Zend Framework Release 1.5 there is a much better way to handle this. You can set
            a default locale which the static <methodname>setDefault()</methodname> method. Of
            course, every unknown or not full qualified locale will also throw an exception.
            <methodname>setDefault()</methodname> should be the first call before you initiate any
            class using <classname>Zend_Locale</classname>. See the following example for details:
        </para>

        <example id="zend.locale.defaultlocale.example-2">
            <title>Setting a default locale</title>

            <programlisting language="php"><![CDATA[
// within the bootstrap file
Zend_Locale::setDefault('de');

// within your model/controller
$date = new Zend_Date();
]]></programlisting>
        </example>

        <para>
            In the case that no locale can be detected, automatically the locale
            <emphasis>de</emphasis> will be used. Otherwise, the detected locale will be used.
        </para>
    </sect2>

    <sect2 id="zend.locale.interoperate">
        <title>ZF Locale-Aware Classes</title>

        <para>
            In the Zend Framework, locale-aware classes rely on <classname>Zend_Locale</classname>
            to automatically select a locale, as explained above. For example, in a Zend Framework
            web application, constructing a date using <classname>Zend_Date</classname> without
            specifying a locale results in an object with a locale based on information provided by
            the current user's web browser.
        </para>

        <example id="zend.locale.interoperate.example-1">
            <title>Dates default to correct locale of web users</title>

            <programlisting language="php"><![CDATA[
$date = new Zend_Date('2006',Zend_Date::YEAR);
]]></programlisting>
        </example>

        <para>
            To override this default behavior, and force locale-aware Zend Framework components to
            use specific locales, regardless of the origin of your website visitors, explicitly
            specify a locale as the third argument to the constructor.
        </para>

        <example id="zend.locale.interoperate.example-2">
            <title>Overriding default locale selection</title>

            <programlisting language="php"><![CDATA[
$usLocale = new Zend_Locale('en_US');
$date = new Zend_Date('2006', Zend_Date::YEAR, $usLocale);
$temp = new Zend_Measure_Temperature('100,10',
                                     Zend_Measure::TEMPERATURE,
                                     $usLocale);
]]></programlisting>
        </example>

        <para>
            If you know many objects should all use the same default locale, explicitly specify the
            default locale to avoid the overhead of each object determining the default locale.
        </para>

        <example id="zend.locale.interoperate.example-3">
            <title>Performance optimization when using a default locale</title>

            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale();
$date = new Zend_Date('2006', Zend_Date::YEAR, $locale);
$temp = new Zend_Measure_Temperature('100,10',
                                     Zend_Measure::TEMPERATURE,
                                     $locale);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.frameworkwidelocale">
        <title>Application wide locale</title>

        <para>
            Zend Framework allows the usage of an application wide locale. You simply set an
            instance of <classname>Zend_Locale</classname> to the registry with the key
            'Zend_Locale'. Then this instance will be used within all locale aware classes of
            Zend Framework. This way you set one locale within your registry and then you can forget
            about setting it again. It will automatically be used in all other classes. See the
            below example for the right usage:
        </para>

        <example id="zend.locale.frameworkwidelocale.example">
            <title>Usage of an application wide locale</title>

            <programlisting language="php"><![CDATA[
// within your bootstrap
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// within your model or controller
$date = new Zend_Date();
// print $date->getLocale();
echo $date->getDate();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.formatoptions">
        <title>Zend_Locale_Format::setOptions(array $options)</title>

        <para>
            The 'precision' option of a value is used to truncate or stretch extra digits. A value
            of '-1' disables modification of the number of digits in the fractional part of the
            value. The 'locale' option helps when parsing numbers and dates using separators and
            month names. The date format 'format_type' option selects between
            <acronym>CLDR</acronym>/ISO date format specifier tokens and <acronym>PHP</acronym>'s
            date() tokens. The 'fix_date' option enables or disables heuristics that attempt to
            correct invalid dates. The 'number_format' option specifies a default number format for
            use with <methodname>toNumber()</methodname> (see <xref
                linkend= "zend.locale.number.localize"/>).
        </para>

        <para>
            The 'date_format' option can be used to specify a default date format string, but beware
            of using getDate(), checkdateFormat() and getTime() after using setOptions() with a
            'date_format'. To use these four methods with the default date format for a locale, use
            array('date_format' => null, 'locale' => $locale) for their options.
        </para>

        <example id="zend.locale.formatoptions.example-1">
            <title>Dates default to correct locale of web users</title>

            <programlisting language="php"><![CDATA[
Zend_Locale_Format::setOptions(array('locale' => 'en_US',
                                     'fix_date' => true,
                                     'format_type' => 'php'));
]]></programlisting>
        </example>

        <para>
            For working with the standard definitions of a locale the option
            <constant>Zend_Locale_Format::STANDARD</constant> can be used. Setting the option
            <constant>Zend_Locale_Format::STANDARD</constant> for <code>date_format</code> uses the
            standard definitions from the actual set locale. Setting it for number_format uses the
            standard number format for this locale. And setting it for locale uses the standard
            locale for this environment or browser.
        </para>

        <example id="zend.locale.formatoptions.example-2">
            <title>Using STANDARD definitions for setOptions()</title>

            <programlisting language="php"><![CDATA[
Zend_Locale_Format::setOptions(array('locale' => 'en_US',
                                     'date_format' => 'dd.MMMM.YYYY'));
// overriding the global set date format
$date = Zend_Locale_Format::getDate('2007-04-20',
                                    array('date_format' =>
                                              Zend_Locale_Format::STANDARD);

// global setting of the standard locale
Zend_Locale_Format::setOptions(array('locale' => Zend_Locale_Format::STANDARD,
                                     'date_format' => 'dd.MMMM.YYYY'));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.cache">
        <title>Speed up Zend_Locale and its subclasses</title>

        <para>
            <classname>Zend_Locale</classname> and its subclasses can be speed up by the usage of
            <classname>Zend_Cache</classname>. Use the static method
            <methodname>Zend_Locale::setCache($cache)</methodname> if you are using
            <classname>Zend_Locale</classname>. <classname>Zend_Locale_Format</classname> can be
            speed up the using the option <code>cache</code> within
            <classname>Zend_Locale_Format::setOptions(array('cache' => $adapter));</classname>.
            If you are using both classes you should only set the cache for
            <classname>Zend_Locale</classname>, otherwise the last set cache will overwrite the
            previous set cache. For convenience there are also the static methods
            <methodname>getCache()</methodname>, <methodname>hasCache()</methodname>,
            <methodname>clearCache()</methodname> and <methodname>removeCache()</methodname>.
        </para>

        <para>
            When no cache is set, then <classname>Zend_Locale</classname> will automatically set a
            cache itself. Sometimes it is wished to prevent that a cache is set, even if this
            degrades performance. In this case the static
            <methodname>disableCache(true)</methodname> method should be used. It does not only
            disable the actual set cache, without erasing it, but also prevents that a cache is
            automatically generated when no cache is set.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->