<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.filter.set.localizedtonormalized">
    <title>LocalizedToNormalized and NormalizedToLocalized</title>

    <para>
        These two filters can change given localized input to it's normalized representation and
        reverse. They use in Background <classname>Zend_Locale</classname> to do this transformation
        for you.
    </para>

    <sect3 id="zend.filter.set.localizedtonormalized.options">
        <title>
            Supported options for Zend_Filter_LocalizedToNormalized and
            Zend_Filter_NormalizedToLocalized
        </title>

        <para>
            The following options are supported for
            <classname>Zend_Filter_LocalizedToNormalized</classname> and
            <classname>Zend_Filter_NormalizedToLocalized</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>date_format</property></emphasis>: This sets the date format
                    to use for normalization and to detect the localized date format
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>locale</property></emphasis>: This sets the locale to use
                    for normalization and to detect the localized format
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>precision</property></emphasis>: This sets the precision to
                    use for number conversion
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.filter.set.localizedtonormalized.workflow">
        <title>Workflow</title>

        <para>
            Normalization allows your user to enter informations in his own language notation, and
            you can then store the normalized value into your database for example. Localization
            on the other hand allows you to display normalized informations in a localized manner
            to your user.
        </para>

        <note>
            <para>
                Please note that normalization and localization is not equal to translation. These
                filters can not translate strings from one language into another like you could
                expect with months or names of days.
            </para>
        </note>

        <para>
            The following input types can be normalized and localized:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>integer</emphasis>: Integer numbers. Normalization returns the english
                    notation
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>float</emphasis>: Float numbers. Normalization returns the english
                    notation
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>numbers</emphasis>: Other numbers, like real. Normalization returns
                    the english notation
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>time</emphasis>: Time values. The normalized value is a named array
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>date</emphasis>: Date values. The normalized value is a named array
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Any other input will be returned as is, without changing it.
        </para>

        <note>
            <para>
                You should note that normalized output is always given as string. Otherwise your
                environment would transfer the normalized output automatically to the notation used
                by the locale your environment is set to.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.filter.set.localizedtonormalized.numbersnormal">
        <title>Normalization for numbers</title>

        <para>
            Any given number like integer, float or real value, can be normalized. Note, that
            numbers in scientific notation, can actually not be handled by this filter.
        </para>

        <para>
            So how does this normalization work in detail for numbers:
        </para>

        <programlisting language="php"><![CDATA[
// Initiate the filter
$filter = new Zend_Filter_LocalizedToNormalized();
$filter->filter('123.456,78');
// returns the value '123456.78'
]]></programlisting>

        <para>
            Let's expect you have set the locale 'de' as application wide locale.
            <classname>Zend_Filter_LocalizedToNormalized</classname> will take the set locale and
            use it to detect which sort of input you gave. In our example it was a value with
            precision. Now the filter will return you the normalized representation for this value
            as string.
        </para>

        <para>
            You can also control how your normalized number has to look like. Therefor you can give
            all options which are also used by <classname>Zend_Locale_Format</classname>. For
            details about available options take a look into this
            <link linkend="zend.locale.parsing">Zend_Locale chapter</link>.
        </para>

        <para>
            Below is a example with defined precision so you can see how options work:
        </para>

        <programlisting language="php"><![CDATA[
// Numeric Filter
$filter = new Zend_Filter_LocalizedToNormalized(array('precision' => 2));

$filter->filter('123.456');
// returns the value '123456.00'

$filter->filter('123.456,78901');
// returns the value '123456.79'
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.localizedtonormalized.dates">
        <title>Normalization for date and time</title>

        <para>
            Input for date and time values can also be normalized. All given date and time values
            will be returned as array, where each date part is given within a own key.
        </para>

        <programlisting language="php"><![CDATA[
// Initiate the filter
$filter = new Zend_Filter_LocalizedToNormalized();
$filter->filter('12.April.2009');
// returns array('day' => '12', 'month' => '04', 'year' => '2009')
]]></programlisting>

        <para>
            Let's expect you have set the locale 'de' again. Now the input is automatically detected
            as date, and you will get a named array in return.
        </para>

        <para>
            Of course you can also control how your date input looks like with the
            <emphasis>date_format</emphasis> and the <emphasis>locale</emphasis> option.
        </para>

        <programlisting language="php"><![CDATA[
// Date Filter
$filter = new Zend_Filter_LocalizedToNormalized(
    array('date_format' => 'ss:mm:HH')
);

$filter->filter('11:22:33');
// returns array('hour' => '33', 'minute' => '22', 'second' => '11')
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.localizedtonormalized.numberslocal">
        <title>Localization for numbers</title>

        <para>
            Any given number like integer, float or real value, can be localized. Note, that
            numbers in scientific notation, can actually not be handled by this filter.
        </para>

        <para>
            So how does localization work in detail for numbers:
        </para>

        <programlisting language="php"><![CDATA[
// Initiate the filter
$filter = new Zend_Filter_NormalizedToLocalized();
$filter->filter(123456.78);
// returns the value '123.456,78'
]]></programlisting>

        <para>
            Let's expect you have set the locale 'de' as application wide locale.
            <classname>Zend_Filter_NormalizedToLocalized</classname> will take the set locale and
            use it to detect which sort of output you want to have. In our example it was a value
            with precision. Now the filter will return you the localized representation for this
            value as string.
        </para>

        <para>
            You can also control how your localized number has to look like. Therefor you can give
            all options which are also used by <classname>Zend_Locale_Format</classname>. For
            details about how these options are used take a look into this
            <link linkend="zend.locale.parsing">Zend_Locale chapter</link>.
        </para>

        <para>
            Below is a example with defined precision so you can see how options
            work:
        </para>

        <programlisting language="php"><![CDATA[
// Numeric Filter
$filter = new Zend_Filter_NormalizedToLocalized(array('precision' => 2));

$filter->filter(123456);
// returns the value '123.456,00'

$filter->filter(123456.78901);
// returns the value '123.456,79'
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.normalizedtolocalized.dates">
        <title>Localization for date and time</title>

        <para>
            Normalized for date and time values can also be localized. All given date and time
            values will be returned as string, with the format defined by the set locale.
        </para>

        <programlisting language="php"><![CDATA[
// Initiate the filter
$filter = new Zend_Filter_NormalizedToLocalized();
$filter->filter(array('day' => '12', 'month' => '04', 'year' => '2009');
// returns '12.04.2009'
]]></programlisting>

        <para>
            Let's expect you have set the locale 'de' again. Now the input is automatically detected
            as date, and will be returned in the format defined by the locale 'de'.
        </para>

        <para>
            Of course you can also control how your date input looks like with the
            <emphasis>date_format</emphasis>, and the <emphasis>locale</emphasis> option.
        </para>

        <programlisting language="php"><![CDATA[
// Date Filter
$filter = new Zend_Filter_LocalizedToNormalized(
    array('date_format' => 'ss:mm:HH')
);

$filter->filter(array('hour' => '33', 'minute' => '22', 'second' => '11'));
// returns '11:22:33'
]]></programlisting>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->