<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.locale.functions">
    <title>Using Zend_Locale</title>

    <para>
        <classname>Zend_Locale</classname> also provides localized information about locales for
        each locale, including localized names for other locales, days of the week, month names,
        etc.
    </para>

    <sect2 id="zend.locale.copying">
        <title>Copying, Cloning, and Serializing Locale Objects</title>

        <para>
            Use <ulink url="http://php.net/language.oop5.cloning">object cloning</ulink> to
            duplicate a locale object exactly and efficiently. Most locale-aware methods also accept
            string representations of locales, such as the result of
            <code>$locale->toString()</code>.
        </para>

        <example id="zend.locale.copying.example-1">
            <title>clone</title>

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

// Save the $locale object as a serialization
$serializedLocale = $locale->serialize();
// re-create the original object
$localeObject = unserialize($serializedLocale);

// Obtain a string identification of the locale
$stringLocale = $locale->toString();

// Make a cloned copy of the $local object
$copiedLocale = clone $locale;

print "copied: ", $copiedLocale->toString();

// PHP automatically calls toString() via __toString()
print "copied: ", $copiedLocale;
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.equals">
        <title>Equality</title>

        <para>
            <classname>Zend_Locale</classname> also provides a convenience function to compare two
            locales. All locale-aware classes should provide a similar equality check.
        </para>

        <example id="zend.locale.equals.example-1">
            <title>Check for equal locales</title>

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

// Check if locales are equal
if ($locale->equals($mylocale)) {
    print "Locales are equal";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getdefault">
        <title>Default locales</title>

        <para>
            The method <methodname>getDefault()</methodname> returns an array of relevant locales
            using information from the user's web browser (if available), information from the
            environment of the host server, and Zend Framework settings. As with the constructor
            for <classname>Zend_Locale</classname>, the first parameter selects a preference of
            which information to consider <link
                linkend="zend.locale.selection">(<constant>BROWSER</constant>,
                <constant>ENVIRONMENT</constant>, or <code>FRAMEWORK)</code></link> first. The
            second parameter toggles between returning all matching locales or only the first/best
            match. Locale-aware components normally use only the first locale. A quality rating is
            included, when available.
        </para>

        <example id="zend.locale.getdefault.example-1">
            <title>Get default locales</title>

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

// Return all default locales
$found = $locale->getDefault();
print_r($found);

// Return only browser locales
$found2 = $locale->getDefault(Zend_Locale::BROWSER,TRUE);
print_r($found2);
]]></programlisting>
        </example>

        <para>
            To obtain only the default locales relevant to the <link
                linkend="zend.locale.selection"><constant>BROWSER</constant>,
                <constant>ENVIRONMENT</constant>, or <constant>FRAMEWORK</constant></link>, use
            the corresponding method:

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>getEnvironment()</methodname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getBrowser()</methodname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getLocale()</methodname>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.locale.setlocale">
        <title>Set a new locale</title>

        <para>
            A new locale can be set with the function <methodname>setLocale()</methodname>. This
            function takes a locale string as parameter. If no locale is given, a locale is
            <link linkend="zend.locale.selection">automatically selected</link>.
        </para>

        <example id="zend.locale.setlocale.example-1">
            <title>setLocale</title>

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

// Actual locale
print $locale->toString();

// new locale
$locale->setLocale('aa_DJ');
print $locale->toString();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getlocale">
        <title>Getting the language and region</title>

        <para>
            Use <methodname>getLanguage()</methodname> to obtain a string containing the two
            character language code from the string locale identifier. Use
            <methodname>getRegion()</methodname> to obtain a string containing the two character
            region code from the string locale identifier.
        </para>

        <example id="zend.locale.getlocale.example-1">
            <title>getLanguage and getRegion</title>

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

// if locale is 'de_AT' then 'de' will be returned as language
print $locale->getLanguage();

// if locale is 'de_AT' then 'AT' will be returned as region
print $locale->getRegion();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getlocaletoterritory">
        <title>Get the locale by giving a territory</title>

        <para>
            When you only have the territory or country then it's also possible to get a locale
            from that information. You can manually search if there is a locale for this territory
            by using <methodname>getLocaleToTerritory()</methodname>. This method returns a
            locale for the given territory or <constant>NULL</constant> when there was has no locale
            been found.
        </para>

        <example id="zend.locale.setlocale.example-1">
            <title>getLocaleToTerritory</title>

            <programlisting language="php"><![CDATA[
$locale = Zend_Locale::getLocaleToTerritory('US');
// returns 'en_US'
]]></programlisting>
        </example>

        <note>
            <title>Uppercase territories</title>

            <para>
                When you know that you are using a territory, then you should uppercase it.
                Otherwise you could get an in your eyes false locale in return when you use other
                methods. For example: When you give "om" then
                <methodname>getLocaleToTerritory()</methodname> returns you "ar_OM" as it knows that
                you mean a territory. But all other methods will return "om", as it's also a
                language.
            </para><commit_msg>[MANUAL] English:<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.locale.functions">
    <title>Using Zend_Locale</title>

    <para>
        <classname>Zend_Locale</classname> also provides localized information about locales for
        each locale, including localized names for other locales, days of the week, month names,
        etc.
    </para>

    <sect2 id="zend.locale.copying">
        <title>Copying, Cloning, and Serializing Locale Objects</title>

        <para>
            Use <ulink url="http://php.net/language.oop5.cloning">object cloning</ulink> to
            duplicate a locale object exactly and efficiently. Most locale-aware methods also accept
            string representations of locales, such as the result of
            <code>$locale->toString()</code>.
        </para>

        <example id="zend.locale.copying.example-1">
            <title>clone</title>

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

// Save the $locale object as a serialization
$serializedLocale = $locale->serialize();
// re-create the original object
$localeObject = unserialize($serializedLocale);

// Obtain a string identification of the locale
$stringLocale = $locale->toString();

// Make a cloned copy of the $local object
$copiedLocale = clone $locale;

print "copied: ", $copiedLocale->toString();

// PHP automatically calls toString() via __toString()
print "copied: ", $copiedLocale;
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.equals">
        <title>Equality</title>

        <para>
            <classname>Zend_Locale</classname> also provides a convenience function to compare two
            locales. All locale-aware classes should provide a similar equality check.
        </para>

        <example id="zend.locale.equals.example-1">
            <title>Check for equal locales</title>

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

// Check if locales are equal
if ($locale->equals($mylocale)) {
    print "Locales are equal";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getdefault">
        <title>Default locales</title>

        <para>
            The method <methodname>getDefault()</methodname> returns an array of relevant locales
            using information from the user's web browser (if available), information from the
            environment of the host server, and Zend Framework settings. As with the constructor
            for <classname>Zend_Locale</classname>, the first parameter selects a preference of
            which information to consider <link
                linkend="zend.locale.selection">(<constant>BROWSER</constant>,
                <constant>ENVIRONMENT</constant>, or <code>FRAMEWORK)</code></link> first. The
            second parameter toggles between returning all matching locales or only the first/best
            match. Locale-aware components normally use only the first locale. A quality rating is
            included, when available.
        </para>

        <example id="zend.locale.getdefault.example-1">
            <title>Get default locales</title>

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

// Return all default locales
$found = $locale->getDefault();
print_r($found);

// Return only browser locales
$found2 = $locale->getDefault(Zend_Locale::BROWSER,TRUE);
print_r($found2);
]]></programlisting>
        </example>

        <para>
            To obtain only the default locales relevant to the <link
                linkend="zend.locale.selection"><constant>BROWSER</constant>,
                <constant>ENVIRONMENT</constant>, or <constant>FRAMEWORK</constant></link>, use
            the corresponding method:

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>getEnvironment()</methodname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getBrowser()</methodname>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <methodname>getLocale()</methodname>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.locale.setlocale">
        <title>Set a new locale</title>

        <para>
            A new locale can be set with the function <methodname>setLocale()</methodname>. This
            function takes a locale string as parameter. If no locale is given, a locale is
            <link linkend="zend.locale.selection">automatically selected</link>.
        </para>

        <example id="zend.locale.setlocale.example-1">
            <title>setLocale</title>

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

// Actual locale
print $locale->toString();

// new locale
$locale->setLocale('aa_DJ');
print $locale->toString();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getlocale">
        <title>Getting the language and region</title>

        <para>
            Use <methodname>getLanguage()</methodname> to obtain a string containing the two
            character language code from the string locale identifier. Use
            <methodname>getRegion()</methodname> to obtain a string containing the two character
            region code from the string locale identifier.
        </para>

        <example id="zend.locale.getlocale.example-1">
            <title>getLanguage and getRegion</title>

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

// if locale is 'de_AT' then 'de' will be returned as language
print $locale->getLanguage();

// if locale is 'de_AT' then 'AT' will be returned as region
print $locale->getRegion();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.locale.getlocaletoterritory">
        <title>Get the locale by giving a territory</title>

        <para>
            When you only have the territory or country then it's also possible to get a locale
            from that information. You can manually search if there is a locale for this territory
            by using <methodname>getLocaleToTerritory()</methodname>. This method returns a
            locale for the given territory or <constant>NULL</constant> when there was has no locale
            been found.
        </para>

        <example id="zend.locale.getlocaletoterritory.example-1">
            <title>getLocaleToTerritory</title>

            <programlisting language="php"><![CDATA[
$locale = Zend_Locale::getLocaleToTerritory('US');
// returns 'en_US'
]]></programlisting>
        </example>

        <note>
            <title>Uppercase territories</title>

            <para>
                When you know that you are using a territory, then you should uppercase it.
                Otherwise you could get an in your eyes false locale in return when you use other
                methods. For example: When you give "om" then
                <methodname>getLocaleToTerritory()</methodname> returns you "ar_OM" as it knows that
                you mean a territory. But all other methods will return "om", as it's also a
                language.
            </para>
{'fraction_non_alphanumeric': 0.11096265615605586, 'fraction_numerical': 0.003206627029193667, 'mean_word_length': 2.3761840324763193, 'pattern_counts': {'":': 0, '<': 309, '<?xml version=': 2, '>': 333, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '827312', 'n_tokens_mistral': 4027, 'n_tokens_neox': 3816, 'n_words': 1228}