1.Introduction.md

Introduction

MultiLocale is a Zend Framework 2 module to automatically detect a locale for your application. It uses a variety of pluggable strategies to search for a valid locale. MultiLocale features a default locale, a set of supported locales and locale aliases.

Strategies

The strategies are triggered via an event manager. This gives the option to have strategies look very early and others as late as possible. For example, you might first want to search for a cookie, then for a domain name and as last option in the HTTP Accept-Language header.

The strategies can also be called when a locale is found. This is useful for example to write a cookie with the locale when the locale is found through the HTTP Accept-Language header. Or you might want to perform a redirect to the correct domain when a user stated it preferred a certain locale.

Detector options

The detector has a few options to tune the detection mechanism. First, there is a default locale. When every strategy sought for a locale, but did not find any, the default locale will be set. There is also a list of supported locales. Your application will probably not support every available locale, so you could define a set and MultiLocale tries to identify the best match. Aliases are possible to transform language codes into full locales. For example you can say if the code "en" is matched, the locale "en-US" will be used.

Usage

Open the configuration file (at config/autoload/multilocale.global.php). In this file the complete behaviour of MultiLocale can be tuned.

Default locale

If you remove the // before the 'default' line, you are able to set the default locale for your application

'default' => 'en-US'

Supported locales

If you only want to have a specified set of locales your application supports, you can remove the // before the 'supported'. In the array you can specify the list you want to support. Keep in mind the order of the list is important. If a strategy can detect multiple locales (like with the HTTP Accept-Language header) the first match in the list will be chosen.

'supported' => array('en-US', 'en-GB', 'en');

Strategy configuration

The strategies are configurable per strategy. You can also define the priority of the strategies used. By default, you can specify a string value for the strategy's name.

'strategies' => array('uripath', 'acceptlanguage');

You can also use an array for the strategy's options and priority.

'strategies' => array(
    array(
        'name'     => 'uripath',
        'options'  => array(/* ... */),
        'priority' => 1
    ),

    array(
        'name'     => 'acceptlanguage',
        'priority' => 0.5
    )
)

More information about strategies can be found at the strategies page.