README

…for F3 polyglots!

This plugin for Fat-Free Framework provides a URL-friendly mean to localize your web site/app.

Demo: here.

Basic usage
Root URL
Advanced usage
Rerouting
Migration mode
Strict mode
Passthru mode
API
Potential improvements

Basic usage

Step 1:

Declare the languages of your app in the MULTILANG.languages variable:

$f3->set('MULTILANG.languages',array(
  'en' => 'en-GB,en-US,en',
  'ja' => 'ja-JP,ja',
  'es' => 'es-ES,es'
));

The same declaration can be achieved in a configuration file using the following syntax:

[MULTILANG.languages]
en = en-GB, en-US, en
ja = ja-JP, ja
es = es-ES, es

NB1: each entry maps a language identifier (en, ja, es) to one or more locales. The language identifiers are arbitrary (english, en-GB, japan, etc) but remember: they will appear in your URLs.

NB2: The first defined language is considered as the primary language, which means it is set as FALLBACK. In our example, on a japanese page, the locales and dictionaries would be searched in the following order: ja-JP, ja, en-GB, en, en-US.

NB3: It is strongly advised to include a country-independant language code (en, ja, es, etc...) in the list of locales for a better browser language detection.

Step 2:

Start the plugin by instantiating the class, just before the call to $f3->run:

$f3->config('config.ini');
Multilang::instance();
$f3->run();

That's it!

Now every existing URL has been duplicated into as many languages you've declared, using identifiers as prefixes:

         => /en/contact
/contact => /ja/contact
         => /es/contact

How about the original URLs? => They have been removed.
How about the original root /? => It autodetects the browser language. See below

Root URL

By default, the root URL autodetects the browser language and performs a redirection to its root page.

In our example, a Spanish user would be redirected to /es while a Russian user would be redirected to /en (fallback to the primary language).

You can override this default behaviour by setting the MULTILANG.root to a custom handler:

[MULTILANG]
root = App\MyRoot

Use case: display a splash page with the list of available languages.

Advanced usage

(requires the usage of route aliases)

Rewrite URLs

Each translated URL consists of a language identifier followed by the original URL:

/es + /terms-and-conditions = /es/terms-and-conditions

You can customize the second part by setting the MULTILANG.rules variable. For example, in order to translate the Spanish URL above, you could write (assuming the route is named terms):

$f3->set('MULTILANG.rules',array(
  'es' => array(
    'terms' => '/terminos-y-condiciones'
  )
));

The same declaration can be achieved in a configuration file using the following syntax:

[MULTILANG.rules.es]
terms = /terminos-y-condiciones

Exclude a language from a route

When translating a website, you may need to perform a progressive translation, route by route. It could also occur that some parts won't be localized at all (for example a blog).

For this purpose, you can remove a route for a specific language by setting it to FALSE:

[MULTILANG.rules.es]
blog = FALSE

A request to /es/blog will return a 404 error.

Global routes

Some routes have to stay language-independant, for example a captcha doesn't have to be localized. Also back offices often happen to be monolingual.

Those global routes are not rewritten: they keep their original URL. They are defined using the MULTILANG.global variable:

[MULTILANG]
global = captcha
;could also be an array:
global = alias1, alias2, alias3, /admin, /foo/bar

Each entry can be a route alias or a URI prefix.

NB: on a global route, the language is auto-detected by default. So in the case of a monolingual back office, you may need to force the language at the controller level.

Rerouting

If you're using named routes...

$f3->reroute will work as expected, that is to say, it will reroute to the current language URL of the provided named route. E.g:

$f3->reroute('@contact'); // OK => reroute to /xx/contact where xx is the current language

If you're using unnamed routes...

In that case, you have to provide a language-prefixed URL to $f3->reroute:

$f3->reroute('/en/contact'); // OK
$f3->reroute('/contact'); // Error => 404 Not Found

If you'd prefer to give the short URL to the framework and have it automatically prefix the URL with the current language, use the $ml->reroute method provided by the plugin:

$ml->reroute('/en/contact'); // OK
$ml->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

In the situation where you'd like to quickly localize an existing project with unnamed routes, and would prefer to avoid having to rewrite every $f3->reroute into $ml->reroute, you can simply use the framework's ONREROUTE hook:

$f3->set('ONREROUTE',function($url,$permanent) use($f3,$ml){
  $f3->clear('ONREROUTE');
  $ml->reroute($url,$permanent);
});

// then in your controller, existing reroutes will keep on working:
$f3->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

Migration mode

When translating an existing monolingual site, it is often interesting to redirect the old monolingual URIs to the new multilingual ones. The plugin does it automatically for you if you set MULTILANG.migrate to TRUE.

Example:

when migration mode is disabled, /contact throws a 404 error
when migration mode is enabled, /contact performs a 301 redirection to /en/contact (the primary language)

Strict mode

When URLs are rewritten, an error is thrown if duplicate URLs are detected. E.g:

[MULTILANG.rules.en]
contact = /contact
blog = /contact

This behaviour is called "strict mode" and is enabled by default.

You can disable it by setting MULTILANG.strict to FALSE, in which case no error will be thrown.

Passthru mode

When starting a new monolingual project, it may be interesting to keep the dependency to the Multilang plugin while not altering routes, just in case one day the project turns multilingual.

The passthru mode is meant for this situation. Set MULTILANG.passthru to TRUE to enable it.

When the passthru mode is enabled, the plugin doesn't do much:

it reads the MULTILANG configuration variable
it sets $f3->LANGUAGE accordingly to the primary language
it leaves the framework routes untouched
it provides its usual public methods and properties

API

$ml = Multilang::instance();

current

Return the language detected for the current URL

echo $ml->current;// ja

primary

Return the name of the primary language

echo $ml->primary;// en

auto

TRUE if language has been auto-detected

echo $ml->auto;//FALSE

passthru

TRUE if passthru mode is enabled

echo $ml->passthru;//FALSE

locale()

Return the currently selected locale

NB: the value returned by this function can be different from what you're expecting if the locales configured in MULTILANG.languages are not present on your system.

echo $ml->locale();// en_GB.UTF-8

displayLanguage( $iso )

Return the language name corresponding to the given ISO code

NB: the name is localized if the intl extension is installed, otherwise it is returned in English.

// on a Danish route (with intl)
echo $ml->displayLanguage('fr');// fransk

// on a Russian route (with intl)
echo $ml->displayLanguage('fr');// французский

// on any route (without intl)
echo $ml->displayLanguage('fr');// French

displayCountry( $iso )

Return the country name corresponding to the given ISO code

NB: the name is localized if the intl extension is installed, otherwise it is returned in English.

// on a Danish route (with intl)
echo $ml->displayCountry('ru');// Rusland

// on a Russian route (with intl)
echo $ml->displayCountry('ru');// Россия

// on any route (without intl)
echo $ml->displayCountry('ru');// Russia

display( $iso )

Alias for displayLanguage( $iso ) [deprecated]

languages()

Return the list of available languages

$ml->languages();// array('en','ja','es')

locales()

Return the list of available locales (indexed by languages)

$ml->locales();
/* array(
    'en' => 'en-GB,en-US,en',
    'ja' => 'ja-JP,ja',
    'es' => 'es-ES,es'
)*/

aliases()

Return the list of all aliases

(even those not available for the current language)

$ml->aliases();// array('terms','blog','captcha')

isLocalized( $name, $lang=NULL )

Check if a route is localized in a given language (default=current)

(localized = not global nor excluded)

$ml->isLocalized('terms');// TRUE (current language)
$ml->isLocalized('terms','es');// TRUE
$ml->isLocalized('blog','es');// FALSE (excluded for Spanish)
$ml->isLocalized('captcha');// FALSE (global)
$ml->isLocalized('foo');// FALSE (non-existent route)

isGlobal( $name )

Check if a route is global

$ml->isGlobal('captcha');// TRUE

alias( $name, $params=NULL, $lang=NULL )

Assemble url from alias name

This function is a language-aware version of $f3->alias().

echo $ml->alias('terms',NULL,'es');// /es/terminos-y-condiciones [local route]
echo $ml->alias('captcha');// /captcha [global route]

reroute( $url=NULL, $permanent=FALSE )

Reroute to specified URI

This function is a language-aware version of $f3->reroute().

Use it if you want an automatic language prefix on unnamed routes. Cf. rerouting.

$ml->reroute('/en/contact'); // OK
$ml->reroute('/contact'); // OK => reroute to /xx/contact where xx is the current language

Potential improvements

Allow domain level recognition (mydomain.jp/es, or jp/es.mydomain.com)
Hook on "run" event if an event system is implemented in F3 core.

xfra35 / f3-multilang

Maintainers

Details