sjaakp / yii2-polyglot
Ultralight language chooser for the Yii 2.0 framework
Installs: 171
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 0
Type:yii2-extension
Requires
- php: >=7.0.0
- yiisoft/yii2: ~2.0.14
This package is auto-updated.
Last update: 2024-10-29 14:19:38 UTC
README
Ultralight language chooser for Yii2
yii2-polyglot is an application component plus two widgets with flag buttons to choose the application language. It can be used in the Yii 2.0 PHP Framework.
yii2-polyglot was developed as an alternative to other language choosers, which in my opinion are often overly complex.
yii2-polyglot lets the user choose her favourite language by clicking on a flag button. The chosen language becomes the site's main language and is stored in a cookie.
A demonstration of Yii2-polyglot is here.
Installation
Install yii2-polyglot in the usual way with Composer.
Add the following to the require section of your composer.json
file:
"sjaakp/yii2-polyglot": "*"
or run:
composer require sjaakp/yii2-polyglot
You can manually install yii2-polyglot by downloading the source in ZIP-format.
Using yii2-polyglot
First of all, Polyglot should be installed as an application component.
This is done
in the main configuration file, usually called web.php
or main.php
in the config
directory. Add the following to the configuration array:
<?php
'components' => [
// ... other components, like 'cache' and 'errorHandler'
'polyglot' => [
'class' => 'sjaakp\polyglot\Polyglot',
'languages' => [
'en-US' => 'English',
'de-DE' => 'Deutsch',
'fr-FR' => 'Français',
// ... more languages
]
],
// ... even more components
The language
property is an array of the languages (or more correctly the locales)
the web site supports. The keys of this array are the names of the locales in
the ICU-format, just like Yii recommends.
One of the keys should be the same as the
language
-property of the application.
The values of the array should be one of the following:
-
string
human-readable name of the language. It appears as popup tooltip. -
array
with two keys:"label"
the human-readable language name;"flag"
the name of the flag that will be displayed, without the.png
-part.
So, to show the Dutch language with the Belgian flag, we would use:
<php
'components' => [
// ... other components, like 'cache' and 'errorHandler'
'polyglot' => [
'class' => 'sjaakp\polyglot\Polyglot',
'languages' => [
'en-US' => 'English',
// ... more languages
'nl-NL' => [
'label' => 'Nederlands',
'flag' => 'be'
]
]
],
// ... even more components
If the array value is just a string
, Polyglot tries to devise the flag name itself.
A bunch of flags (247 of them) can be found in yii2-polyglot's assets/flags
directory.
They are made by famfamfam, by the way.
Bootstrap
Polyglot has to be bootstrapped. Do this by adding the following to the application configuration array:
<php
'bootstrap' => [
'polyglot',
]
There probably already is a bootstrap
property in your configuration file; just
add 'polyglot'
to it.
Polyglot options
Apart from the languages-settings, Polyglot has three more options:
- useCookie
bool
If set tofalse
, Polyglot will not store the preferred language in a cookie, but in the PHP session. As a consequence, the language choice will only persist for one session. Default:true
. - cookieName
string
Also used as the session key if useCookie isfalse
. Default:"polyglot"
. - cookieStamina
integer
Cookie expiration time in seconds. Default:31536000
(one year).
Widgets
There are two widgets in the yii2-polyglot package. PolyglotButtons displays the
language options as a row of flag buttons. PolyglotDropdown is a dropdown menu.
Rendering a yii2-polyglot widget anywhere in a View
is just a matter of:
<?php
use sjaakp\polyglot\PolyglotButtons;
?>
...
<?= PolyglotButtons::widget() ?>;
...
Or:
<?php
use sjaakp\polyglot\PolyglotDropdown;
?>
...
<?= PolyglotDropdown::widget() ?>;
...
As you will most likely want to have the Polyglot widget on all of your pages, the preferable place for a widget would be the layout viewfile (or one of the layout viewfiles).
Widget options
PolyglotButtons and PolyglotDropdown have the following options:
- options
array
HTML options for the surrounding element. Default:[]
. - buttonOptions
array
HTML options for the individual flag buttons. Default:[]
. - toggleOptions
array
(PolyglotDropdown only) HTML options for the toggle button. Default:['class' => 'nav-link']
.