Language/Localization
FUEL CMS 1.0 now provides basic multi-language support through the CMS for pages and modules. You can configure the number of supported languages in the FUEL config by adding to the $config['languages'] parameter. The Fuel_language class can then be used to help set and retrieve language information.
Creating a Multi-language Website
There are a few different ways to add multi-language support to your website:
CodIgniter's Language Class
CodeIgniter comes with a Language class which can is fully available for you to leverage in your site.
CMS Pages
When multiple languages are configured in the FUEL config, you will see an additional drop down when editing or creating a page in the CMS. Each page location can have multiple languages assigned to it. There are 2 methods in which to access the language version of a page:
Segment Method
To use the segment method, set the language_mode configuration parameter to segment or both in the MY_fuel.php file like so:
$config['language_mode'] = 'segment';
To display the different language versions of the page using the segment method, you can insert the language code at the beginning of the URI like so:
http://localhost/es/about/history
Query String Method
To use the query string method, set the language_mode configuration parameter to query_string or both in the MY_fuel.php file like so:
$config['language_mode'] = 'query_string';
To display the different language versions of the page using the query string method, you can pass the lang query string parameter like so:
http://localhost/about/history?lang=es
Additionally you can set the language of your site for the current user as follows:
$this->fuel->language->set_selected('es');
That user is then cookied to use that language going forward.
Configuring Language Options in the CMS
If you want to enable the ability to control the number of languages supported in the CMS, you can leverage Settings and use a "keyval" field type:
$config['settings'] = array();
$config['settings']['languages'] = array(
'type' => 'keyval',
'fields' => array(
'key' => array('ignore_representative' => TRUE),
'label' => array('ignore_representative' => TRUE),
),
'class' => 'repeatable',
'repeatable' => TRUE,
'ignore_representative' => TRUE
);
This would create a field under the Settings area in the CMS for you to enter information. Values would look like the following:
english:English de:German uk:UK fr:French es:Spanish
View Pages
Additionally, if your pages are using views and there is a language value set by the user using Fuel_language, it will first look for a view file in the views/language/{language}/ folder and if it doesn't find it, it will default to just the views folder.
CMS Modules
Blocks, Navigation and your own custom simple modules behave a little differently then the Page module. A new record must be created for each language version. These modules have a field name of language that will appear if more then one language is configured. For Blocks and Navigation, the fuel_blocks and fuel_nav functions have a "language" parameter you can specify which will pull blocks or menu items specific to that language.
This field name can be configured by specifying the simple module's language_col parameter.
Changing the Language Displayed in the CMS
The default installation of FUEL CMS currently only comes with the English language. However, localization efforts are underway on the FUEL CMS Languages GitHub repo. If you are interested in helping out with language support, just let us know or send us a pull request (we love those).
To add a language to FUEL, you must download the latest 1.0 language folder (if available). and place it's contents in the fuel/modules/fuel/language folder. Then, you can set the $config['language'] in the fuel/application/config/config.php file to match the name of the language folder you downloaded. Alternatively, you may click on your user name in the upper right corner of the CMS, and then change the language associated with your user login.
The following are some key areas in which you can utilize FUEL's localization functionality.
The lang() Function
The lang() overwrites the CodeIgniter lang() function to provide the added benefits of passing arguments to your language files (uses sprintf() function).
The json_lang() Function
The json_lang() function allows for language values to be passed to the javascript. This function creates a Javascript JSON object based on an array of language key values.
The detect_lang Function:
The detect_lang() function detects any specified language settings pulling from the URI, query string and then the user's browser settings.
Form_builder Class
The Form_builder class is used throughout FUEL CMS to create the forms used to manage module data. To allow for the localized labels in the module forms, the lang_prefix property can be used and will look for labels in language files using the format form_label_{literal}{field_name}{/literal}, if not label value is supplied.
Data_table Class
Similar to the Form_builder class, the Data_table class also has a lang_prefix property. This prefix is used for localizing the table column headers. The prefix is set in FUEL to be the same as the Form_builder's which is form_label_.
The js_localized Module Property
The js_localized property can be added to your modules if you have have javascript that needs to use some localized text. You can provide it an array of language key values and it will be added to the list of language keys that get translated into a JSON object for your javascript files to consume. If you are using a jqx type controller that extends the BaseFuelController.js, there will be a localized property and a lang() method on the controller that provides access to the JSON language object.