kohana-multilang/README.md

121 lines
5.0 KiB
Markdown
Raw Permalink Normal View History

# Kohana Multilang Module 3.0
2011-03-06 19:48:30 +02:00
!!! NEW VERSION 3.0 !!!
2011-03-06 19:48:30 +02:00
Multilingual module for the Kohana PHP Framework, version 3.3
2011-03-06 19:48:30 +02:00
## Features
2011-06-26 20:54:27 +03:00
* Language segment in uri. Can be optional for the default language
2011-03-06 19:48:30 +02:00
* Works with normal routes
2011-06-26 20:54:27 +03:00
* Custom routes for each language
* Auto language detection for the homepage (headers then cookie)
* Language selector menu
2011-03-06 19:48:30 +02:00
## Usage
### Configuration
return array(
2011-06-26 20:54:27 +03:00
'default' => 'en', // The default language code
'cookie' => 'lang', // The cookie name
'hide_default' => FALSE, // Hide the language code for the default language
'auto_detect' => TRUE, // Auto detect the user language on the homepage
2011-03-06 19:48:30 +02:00
/**
* 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'),
2011-03-06 20:19:25 +02:00
'label' => 'français',
2011-03-06 19:48:30 +02:00
),
'de' => array(
'i18n' => 'de_DE',
'locale' => array('de_DE.utf-8'),
'label' => 'deutsch',
),
*/
),
);
2011-07-01 20:14:50 +03:00
The default route is special and an example is provided in the init.php file of this module. It is recommended to comment it there and copy it in your bootstrap.
2011-03-06 19:48:30 +02:00
2011-03-06 20:19:25 +02:00
### Example
2011-06-26 20:54:27 +03:00
If you try to access `http://www.domain.tld/`, the module will redirect it to `http://www.domain.tld/en/` if the hide_default option is set to FALSE.
2011-03-06 20:19:25 +02:00
Let's say we have a product page, with kohana 3 we'd have something like :
2011-06-26 20:54:27 +03:00
Route::set('product.details', 'products/<product_id>-<product_slug>', array(
'product_id' => '[0-9]+',
'product_slug' => '.+',
))->defaults(array(
'controller' => 'Product',
2011-06-26 20:54:27 +03:00
'action' => 'details',
'product_id' => NULL,
'product_slug' => '',
));
2011-03-06 20:19:25 +02:00
2011-06-26 20:54:27 +03:00
You can access `http://www.domain.tld/products/12-my-product` with this one.
Now, I want this url in french too, like that: `http://www.domain.tld/fr/products/12-my-product`.
You can use the `Routes` object (notice the S at the end) to set multiple routes for each language.
Let's take a look:
2011-03-06 20:19:25 +02:00
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',
2011-03-06 20:19:25 +02:00
'action' => 'details',
'product_id' => NULL,
'product_slug' => '',
));
2011-06-26 20:54:27 +03:00
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 german with `de`, it will use the default uri, english here.
It is highly recommanded to use reverse routing! 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')`.For the routes than dont need any language code, you can keep the normal kohana syntax.
If you wanna create a route for only one language, you're gonna have to pass a 4th parameter:
2011-03-06 20:19:25 +02:00
2011-06-26 20:54:27 +03:00
Route::set('product.made-in-france', 'produits/fabrique-en-france', NULL, 'fr')
->defaults(array(
'controller' => 'Product',
2011-06-26 20:54:27 +03:00
'action' => 'made_in_france',
2011-03-06 20:46:46 +02:00
));
2011-06-26 20:54:27 +03:00
And then to get it `Route::get('fr.product.made-in-france')` or `Route::get('product.made-in-france', 'fr)`.
The default route is particular and its declaration is set in init.php. Since it doesnt need any translations and has a different behaviour (we wanna keep the trailing slash), we create a custom route that alows all the languages.
2011-03-06 20:19:25 +02:00
### Language selector menu
2011-06-26 20:54:27 +03:00
`Multilang::selector($current)` returns a menu to select the language. It will keep the same page if routes are available for the other languages. The `current` parameter adds the current language in the menu.
2011-03-06 20:51:27 +02:00
You can change the view file `multilang/selector.php`.
2011-03-06 20:19:25 +02:00
2011-03-06 20:46:46 +02:00
### Misc
2011-03-06 20:19:25 +02:00
2011-06-26 20:54:27 +03:00
To get the current language, you can use `Request::$lang`.
2011-03-06 20:19:25 +02:00
### Input
If you have any suggestions, found a bug or anything, feel free to share.
2011-03-06 20:46:46 +02:00
### How it works
2011-06-26 20:54:27 +03:00
We change the Request to force the detection of a language on the site root. Then if a route is found, we get the language from it with its 'lang' parameter and we initialize.
Each route created with a language code gets another parameter: `lang`. A uri like `products/details` will become `<lang>/products/details`.
But since every multilingual route is unique (except default), the regex part allows only one language code. So we have `array('lang' => 'en')` instead of having something like `array('lang' => '(en|fr|de')`. We could have directly the language code in the uri like `en/products/details` but the lang parameter allows us to easily retrieve the route language and works better with the default route.