Chapter 29. Zend_Locale

Table of Contents

29.1. Introduction
29.1.1. What is Localization
29.1.2. What is a Locale?
29.1.3. How are Locales Represented?
29.1.4. Selecting the Right Locale
29.1.5. Usage of automatic Locales
29.1.6. Using a default Locale
29.1.7. ZF Locale-Aware Classes
29.1.8. Application wide locale
29.1.9. Zend_Locale_Format::setOptions(array $options)
29.1.10. Speed up Zend_Locale and its subclasses
29.2. Using Zend_Locale
29.2.1. Copying, Cloning, and Serializing Locale Objects
29.2.2. Equality
29.2.3. Default locales
29.2.4. Set a new locale
29.2.5. Getting the language and region
29.2.6. Obtaining localized strings
29.2.7. Obtaining translations for "yes" and "no"
29.2.8. Get a list of all known locales
29.3. Normalization and Localization
29.3.1. Number normalization: getNumber($input, Array $options) Precision and Calculations
29.3.2. Number localization
29.3.3. Number testing
29.3.4. Float value normalization
29.3.5. Floating point value localization
29.3.6. Floating point value testing
29.3.7. Integer value normalization
29.3.8. Integer point value localization
29.3.9. Integer value testing
29.3.10. Numeral System Conversion List of supported numeral systems
29.4. Working with Dates and Times
29.4.1. Normalizing Dates and Times
29.4.2. Testing Dates
29.4.3. Normalizing a Time
29.4.4. Testing Times
29.5. Supported locales
29.6. Migrating from previous versions
29.6.1. Migrating from 1.6 to 1.7 or newer Changes when using isLocale() Changes when using getDefault()

29.1. Introduction

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

We need Localization and complementary Internationalization . Both are often abbreviated to L10n and I18n. 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. L10n and I18n compliment each other. Zend Framework provides support for these through a combination of components, including Zend_Locale, Zend_Date, Zend_Measure, Zend_Translate, Zend_Currency, and Zend_TimeSync.

[Tip] Zend_Locale and setLocale()

PHP's documentation states that setlocale() 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 setlocale() in your scripts.

When you are using Zend_Locale you will not have this limitations, because Zend_Locale is not related to or coupled with PHP's setlocale().

29.1.1. What is Localization

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

  • Zend_Locale - Backend support of locales available for localization support within other ZF components.

  • Zend_Translate - Translating of strings.

  • Zend_Date - Localization of dates, times.

  • Zend_Calendar - Localization of calendars (support for non-Gregorian calendar systems)

  • Zend_Currency - Localization of currencies.

  • Zend_Locale_Format - Parsing and generating localized numbers.

  • Zend_Locale_Data - Retrieve localized standard strings as country names, language names and more from the CLDR .

  • TODO - Localization of collations

29.1.2.  What is a Locale?

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 locale-aware. How does the code know which localization the user is expecting?

A locale string or object identifying a supported locale gives Zend_Locale and it's subclasses access to information about the language and region expected by the user. Correct formatting, normalization, and conversions are made based on this information.

29.1.3. How are Locales Represented?

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 language_REGION. Both the language and region parts are abbreviated to alphabetic, ASCII characters.

[Note] Note

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

A user from USA would expect the language English and the region USA, yielding the locale identifier "en_US". A user in Germany would expect the language German and the region Germany, yielding the locale identifier "de_DE". See the list of pre-defined locale and region combinations, if you need to select a specific locale within Zend Framework.

Example 29.1. Choosing a specific locale

$locale = new Zend_Locale('de_DE'); // German language _ Germany


A German user in America might expect the language German and the region USA, 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).

Beware of historical changes, as ZF components do not know about or attempt to track the numerous timezone changes made over many years by many regions. For example, we can see a historical list 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 ZF components will not adjust for these changes, but instead will give the correct time for the timezone using current, modern rules for DST and timezone assignment for geographic regions.

29.1.4. Selecting the Right Locale

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

Example 29.2. Automatically selecting a locale

$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);


The search algorithm used by Zend_Locale for automatic selection of a locale uses three sources of information:

  1. const Zend_Locale::BROWSER - The user's Web browser provides information with each request, which is published by PHP in the global variable HTTP_ACCEPT_LANGUAGE. If no matching locale can be found, then preference is given to ENVIRONMENT and lastly FRAMEWORK.

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

  3. const Zend_Locale::FRAMEWORK - 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 ENVIRONMENT and lastly BROWSER.

29.1.5. Usage of automatic Locales

Zend_Locale 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 getDefault() 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, it's string representation, can be used. This offers simplicity for situations like working with locales which are provided by a browser.

There are three locales which have a slightly different behaviour:

  1. 'browser' - Zend_Locale should work with the information which is provided by the user's Web browser. It is published by PHP in the global variable HTTP_ACCEPT_LANGUAGE.

    If a user provides more than one locale within his browser, Zend_Locale 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 'environment' will automatically be used and returned.

  2. 'environment' - Zend_Locale should work with the information which is provided by the host server. It is published by PHP via the internal function setlocale().

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

  3. 'auto' - Zend_Locale 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.

    If no locale can be detected, it will throw an exception and tell you that the automatic detection has been failed.

Example 29.3. Using automatic locales

// without automatic detection
//$locale = new Zend_Locale(Zend_Locale::BROWSER);
//$date = new Zend_Date($locale);

// with automatic detection
$date = new Zend_Date('auto');


29.1.6. Using a default Locale

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.

In such cases Zend_Locale 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.

Example 29.4. Handling locale exceptions

// 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);


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

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

Example 29.5. Setting a default locale

// within the bootstrap file

// within your model/controller
$date = new Zend_Date();


In the case that no locale can be detected, automatically the locale de will be used. Otherwise, the detected locale will be used.

29.1.7. ZF Locale-Aware Classes

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

Example 29.6. Dates default to correct locale of web users

$date = new Zend_Date('2006',Zend_Date::YEAR);


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

Example 29.7. Overriding default locale selection

$usLocale = new Zend_Locale('en_US');
$date = new Zend_Date('2006', Zend_Date::YEAR, $usLocale);
$temp = new Zend_Measure_Temperature('100,10',


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.

Example 29.8. Performance optimization when using a default locale

$locale = new Zend_Locale();
$date = new Zend_Date('2006', Zend_Date::YEAR, $locale);
$temp = new Zend_Measure_Temperature('100,10',


29.1.8. Application wide locale

Zend Framework allows the usage of an application wide locale. You simply set an instance of Zend_Locale 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:

Example 29.9. Usage of an application wide locale

// 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();


29.1.9. Zend_Locale_Format::setOptions(array $options)

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 CLDR/ISO date format specifier tokens and PHP'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 toNumber() (see Section 29.3.2, “Number localization” ).

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.

Example 29.10. Dates default to correct locale of web users

Zend_Locale_Format::setOptions(array('locale' => 'en_US',
                                     'fix_date' => true,
                                     'format_type' => 'php'));


For working with the standard definitions of a locale the option Zend_Locale_Format::STANDARD can be used. Setting the option Zend_Locale_Format::STANDARD for date_format 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.

Example 29.11. Using STANDARD definitions for setOptions()

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

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


29.1.10. Speed up Zend_Locale and its subclasses

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