…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
  • Rewrite URLs
  • Exclude a language from a route
  • Global routes
• API
• Potential improvements

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.

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

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

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

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.

(requires the usage of route aliases)

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

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.

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

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.

$ml = Multilang::instance();

Return the language detected for the current URL

echo $ml->current;// ja

Return the name of the primary language

echo $ml->primary;// en

TRUE if language has been auto-detected

echo $ml->auto;//FALSE

Return the list of available languages

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

Return the list of all aliases

(even those not available for the current language)

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

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)

Check if a route is global

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