…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
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, esNB1: 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\MyRootUse 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-condicionesWhen 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 = FALSEA 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, /admin, /foo/barEach 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.
$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 languageIn that case, you have to provide a language-prefixed URL to $f3->reroute:
$f3->reroute('/en/contact'); // OK
$f3->reroute('/contact'); // Error => 404 Not FoundIf 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 languageIn 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 languageWhen 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,
/contactthrows a 404 error - when migration mode is enabled,
/contactperforms a 301 redirection to/en/contact(the primary language)
When URLs are rewritten, an error is thrown if duplicate URLs are detected. E.g:
[MULTILANG.rules.en]
contact = /contact
blog = /contactThis 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.
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
MULTILANGconfiguration variable - it sets
$f3->LANGUAGEaccordingly to the primary language - it leaves the framework routes untouched
- it provides its usual public methods and properties
$ml = Multilang::instance();Return the language detected for the current URL
echo $ml->current;// jaReturn the name of the primary language
echo $ml->primary;// enTRUE if language has been auto-detected
echo $ml->auto;//FALSETRUE if passthru mode is enabled
echo $ml->passthru;//FALSEReturn 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-8Return 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');// FrenchReturn 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');// RussiaAlias for displayLanguage( $iso ) [deprecated]
Return the list of available languages
$ml->languages();// array('en','ja','es')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'
)*/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');// TRUEAssemble 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 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- 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent