mirror of
https://github.com/Oreolek/kohana-multilang.git
synced 2024-04-29 23:59:24 +03:00
131 lines
5.6 KiB
Markdown
131 lines
5.6 KiB
Markdown
# Kohana Multilang Module
|
|
|
|
Multilingual module for Kohana PHP Framework, version 3.1
|
|
|
|
Partly based on this module https://github.com/GeertDD/kohana-lang
|
|
|
|
## Features
|
|
|
|
* Language segment in uri
|
|
* Works with normal routes
|
|
* Custom routes for each language (localization or parameters)
|
|
* Auto language detection or cookie
|
|
* Language selection menu
|
|
|
|
## Usage
|
|
|
|
### Configuration
|
|
|
|
return array(
|
|
'default' => 'en', // The default language code
|
|
'cookie' => 'lang', // The cookie name
|
|
/**
|
|
* The allowed languages
|
|
* For each language, you need to give a code (2-5 chars) for the key,
|
|
* the 5 letters i18n language code, the locale and the label for the auto generated language selector menu.
|
|
*/
|
|
'languages' => array(
|
|
/*
|
|
'en' => array(
|
|
'i18n' => 'en_US',
|
|
'locale' => array('en_US.utf-8'),
|
|
'label' => 'english',
|
|
),
|
|
'fr' => array(
|
|
'i18n' => 'fr_FR',
|
|
'locale' => array('fr_FR.utf-8'),
|
|
'label' => 'français',
|
|
),
|
|
'de' => array(
|
|
'i18n' => 'de_DE',
|
|
'locale' => array('de_DE.utf-8'),
|
|
'label' => 'deutsch',
|
|
),
|
|
*/
|
|
),
|
|
);
|
|
|
|
### Example
|
|
|
|
If you try to access `http://www.domain.tld/`, the module will redirect it to `http://www.domain.tld/en/` for example.
|
|
|
|
Let's say we have a product page, with kohana 3 we'd have something like :
|
|
|
|
Route::set('product.details', 'products/<product_id>-<product_slug>', array(
|
|
'product_id' => '[0-9]+',
|
|
'product_slug' => '.+',
|
|
))->defaults(array(
|
|
'controller' => 'product',
|
|
'action' => 'details',
|
|
'product_id' => NULL,
|
|
'product_slug' => '',
|
|
));
|
|
|
|
|
|
If you try to access `http://www.domain.tld/products/12-my-product`, it will redirect to `http://www.domain.tld/en/products/12-my-product`.
|
|
Now, I'm on the same page in french `http://www.domain.tld/fr/products/12-my-product`, but I'd like to translate it and set `produits` instead of `products`. You can use the `Routes` object (notice the S at the end) to set multiple routes for each language.
|
|
|
|
Routes::set('product.details', array(
|
|
'en' => 'products/<product_id>-<product_slug>',
|
|
'fr' => 'produits/<product_id>-<product_slug>',
|
|
), array(
|
|
'product_id' => '[0-9]+',
|
|
'product_slug' => '.+',
|
|
))->defaults(array(
|
|
'controller' => 'product',
|
|
'action' => 'details',
|
|
'product_id' => NULL,
|
|
'product_slug' => '',
|
|
));
|
|
|
|
This creates 2 routes named `en.products.details` and `fr.products.details`. The default language (english here) is required. If we have a third language like `de`, it will use `en`. The thing is, both url `http://www.domain.tld/fr/products/12-my-product` and `http://www.domain.tld/en/produits/12-my-product` will still work. To make sure this is not an issue, you should use reverse routing everywhere. With `Route::get('product/details')->uri(array('product_id' => 12, 'product_slug' => 'my_product'))`, you'll get the complete uri with the current user language code. To get another language, just pass a second parameter to `Route::get('product/details', 'en')`.
|
|
|
|
Now, I got a controller that serves CSS files, I obviously don't need any language specified. To prevent the normal behaviour, just pass `FALSE` as the third parameter to `Route::set` like this :
|
|
|
|
Route::set('file.css', 'static/css/<action>.css', array(
|
|
'action' => '[^/.]+',
|
|
), FALSE)->defaults(array(
|
|
'controller' => 'css',
|
|
'action' => NULL,
|
|
));
|
|
|
|
If you access `http://www.domain.tld/static/css/custom_page.css`, it will not redirect and `Route::get('file.css.custom')->uri(array('action' => 'categories'))` will not return the uri with a language code.
|
|
|
|
### Language selector menu
|
|
|
|
`Multilang::selector($current)` returns a menu to select the language. It will keep the same page. The `current` parameter adds the current language in the menu or not.
|
|
You can change the view file `multilang/selector.php`.
|
|
|
|
### Misc
|
|
|
|
To access the current language, you can use `Request::$lang`.
|
|
|
|
### Input
|
|
|
|
If you have any suggestions, found a bug or anything, feel free to share.
|
|
|
|
|
|
### How it works
|
|
|
|
See https://github.com/GeertDD/kohana-lang
|
|
|
|
#### The URI does not contain a language code
|
|
|
|
If somebody visits `http://www.domain.tld/page`, without a language, the best default language will be found and the user will be redirected to the same URL *with* that language prepended. To find the best language, the following elements are taken into account (in this order):
|
|
|
|
1. a language cookie (set during a previous visit);
|
|
2. the HTTP Accept-Language header;
|
|
3. a hard-coded default language.
|
|
|
|
#### The URI contains a language code
|
|
|
|
1. The language code is chopped off before the request and stored in `Request::$lang`.
|
|
2. `I18n::$lang` is set to the correct target language (from config).
|
|
3. The correct locale is set (from config).
|
|
4. A cookie with the language code is set.
|
|
5. Normal request processing continues.
|
|
|
|
It is important to be aware that the *language part is completely chopped off* of the URI. When normal request processing continues it, it does so with a URI without language. This means that **your routes must not contain a language code. Also, you can create HMVC subrequests without having to worry about adding the current language to the URI.
|
|
|
|
The one thing we still need to take care of then, is that any generated URLs should contain the language. An extension of `URL::site` is created for this. A third argument, `$lang`, is added to `URL::site`. By default, the current language is used (`Request::$lang`). You can also provide another language key as a string, or set the argument to `FALSE` to generate a URL without language.
|