Multilang
…for F3 polyglots!, (*1)
This plugin for Fat-Free Framework provides a URL-friendly mean to localize your web site/app., (*2)
Demo: here., (*3)
Basic usage
Step 1:
Declare the languages of your app in the MULTILANG.languages variable:, (*4)
$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:, (*5)
[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., (*6)
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., (*7)
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., (*8)
Step 2:
Start the plugin by instantiating the class, just before the call to $f3->run:, (*9)
$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:, (*10)
=> /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., (*11)
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)., (*12)
You can override this default behaviour by setting the MULTILANG.root to a custom handler:, (*13)
[MULTILANG]
root = App\MyRoot
Use case: display a splash page with the list of available languages., (*14)
Advanced usage
(requires the usage of route aliases), (*15)
Rewrite URLs
Each translated URL consists of a language identifier followed by the original URL:, (*16)
/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):, (*17)
$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:, (*18)
[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)., (*19)
For this purpose, you can remove a route for a specific language by setting it to FALSE:, (*20)
[MULTILANG.rules.es]
blog = FALSE
A request to /es/blog will return a 404 error., (*21)
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., (*22)
Those global routes are not rewritten: they keep their original URL.
They are defined using the MULTILANG.global variable:, (*23)
[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., (*24)
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., (*25)
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:, (*26)
$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:, (*27)
$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:, (*28)
$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:, (*29)
$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., (*30)
Example:, (*31)
- 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:, (*32)
[MULTILANG.rules.en]
contact = /contact
blog = /contact
This behaviour is called "strict mode" and is enabled by default., (*33)
You can disable it by setting MULTILANG.strict to FALSE, in which case no error will be thrown., (*34)
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., (*35)
The passthru mode is meant for this situation. Set MULTILANG.passthru to TRUE to enable it., (*36)
When the passthru mode is enabled, the plugin doesn't do much:, (*37)
- 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, (*38)
echo $ml->current;// ja
primary
Return the name of the primary language, (*39)
echo $ml->primary;// en
auto
TRUE if language has been auto-detected, (*40)
echo $ml->auto;//FALSE
passthru
TRUE if passthru mode is enabled, (*41)
echo $ml->passthru;//FALSE
locale()
Return the currently selected locale, (*42)
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., (*43)
echo $ml->locale();// en_GB.UTF-8
displayLanguage( $iso )
Return the language name corresponding to the given ISO code, (*44)
NB: the name is localized if the intl extension is installed, otherwise it is returned in English., (*45)
// 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, (*46)
NB: the name is localized if the intl extension is installed, otherwise it is returned in English., (*47)
// 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], (*48)
languages()
Return the list of available languages, (*49)
$ml->languages();// array('en','ja','es')
locales()
Return the list of available locales (indexed by languages), (*50)
$ml->locales();
/* array(
'en' => 'en-GB,en-US,en',
'ja' => 'ja-JP,ja',
'es' => 'es-ES,es'
)*/
aliases()
Return the list of all aliases, (*51)
(even those not available for the current language), (*52)
$ml->aliases();// array('terms','blog','captcha')
isLocalized( $name, $lang=NULL )
Check if a route is localized in a given language (default=current), (*53)
(localized = not global nor excluded), (*54)
$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, (*55)
$ml->isGlobal('captcha');// TRUE
alias( $name, $params=NULL, $lang=NULL )
Assemble url from alias name, (*56)
This function is a language-aware version of $f3->alias()., (*57)
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, (*58)
This function is a language-aware version of $f3->reroute()., (*59)
Use it if you want an automatic language prefix on unnamed routes. Cf. rerouting., (*60)
$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.
Wallogit.com
