NAME
Ado::Plugin::I18n - Internationalization and localization for Ado
SYNOPSIS
This plugin just works. Nothing special needs to be done.
#Override the current language.
#you need to do this only in rare cases (like in an Ado::Command)
$c->language('bg');
#what is my language?
my $current_language = $c->language;DESCRIPTION
Ado::Plugin::I18n localizes your application and site. It altomatically detects the current UserAgent language preferences and selects the best fit from the supported by the application languages. The current language is deteted and set in "around_action" in Mojolicious hook. Various methods for setting the language are supported.
OPTIONS
The following options can be set in etc/ado.conf or in etc/plugins/i18n.conf. You have to create first etc/plugins/i18n.conf so Ado can pick it up. You can enable all supported methods to detect the language in your application.
The methods which will be used to detect and set the current language are as follows:
1. language_from_route, eg. /bg/controller/action
2. language_from_host, eg. fr.example.com
3. language_from_param, eg. ?language=de
4. language_from_cookie, eg. Cookie: language=bg;
5. language_from_headers, eg. Accept-Language: bg,fr;q=0.8,en-us;q=0.5,en;q=0.3Just be careful not to try to set the language in one request using two different methods eg. /bg/controller/action?language=de.
default_language
The default value is en. This language is used when Ado is not able to detect the language using any of the methods enabled by the options below. If you want to set a different language be sure to create a language class in your languages namespace. See also "namespace".
language_from_route
{
language_from_route => 1
...
}This is the first option that will be checked if enabled. The plugin prepares a default set of routes containing information about the language.
/:language GET,OPTIONS
/:language/:controller GET,OPTIONS
/:language/:controller/:action GET,POST,OPTIONS
/:language/:controller/:action/:id GET,PUT,DELETE,OPTIONSThe language will be detected from current routes eg. /bg/news/read/1234 and put into the stash. Default value is 1.
language_from_host
{
language_from_host => 1,
language_from_route => 1,
...
}This is the second option that will be checked if enabled. If you use languages as subdomains make sure to disable language_from_route or do not construct routes containing languages (eg. fr.example.com/en). Default value is 1.
language_from_param
{
language_from_param => 1,
language_from_host => 0,
language_from_route => 0,
...
}This is the third option that will be checked if enabled and if the language is not yet detected using some of the previous methods. Make sure to not construct urls like fr.example.com?language=de or even fr.example.com/bg?language=de. The result is usually not what you want. Default value is 1.
language_from_cookie
{
language_from_cookie => 1,
language_from_param => 1,
language_from_host => 0,
language_from_route => 0,
...
}This is the fourth option that will be checked if enabled and if the language is not yet detected using some of the previous methods. This option is most suitable for applications which expect to find a cookie with name "language" and value one of the supported languages. Default value is 1.
language_from_headers
{
language_from_headers => 1
language_from_cookie => 1,
language_from_param => 1,
language_from_host => 0,
language_from_route => 0,
...
}This is the fifth option that will be checked if enabled and if the language is not yet detected using some of the previous methods. It is best to keep this option enabled. Default value is 1.
language_param
#language_param=> 'l'
current language is <%= $l %>
Cookie: l=bg;
#language_param=> 'lang'
current language is <%= $lang %>
Cookie: lang=bg;The name of the parameter(key) used in language_from_param, language_from_route and language_from_cookie. this is also the key used in the $c->stash. Default value is "language".
namespace
The namespace used for language classes. Default value is Ado::I18n. You rarely will want to change this.
HELPERS
Ado::Plugin::I18n exports the following helpers for use in Ado::Control methods and templates.
l
Wrapper for "maketext" in Locale::Maketext.
$c->render(text => $c->l('hello', $c->user->name));
<%= l('hello', user->name) %>language
Allows you to (re)set the current language. You should not need to use this helper! It is called automatically in "around_action" in Mojolicious hook. Note however that if you render a template directly (without controller) you need to call it in the template. See templates/добре/ок.html.ep for an example.
% language('bg');TEMPLATES
Ado::Plugin::I18n contains one embeded template.
partials/language_menu.html.ep
Generates HTML for a language menu. If you want to modify the template you can inflate all templates and do that. A usage example can be found at http://localhost:3000 after starting ado.
berov@u165:~/opt/public_dev/Ado$ bin/ado inflate
...
[exist] /home/berov/opt/public_dev/Ado/templates/partials
[write] /home/berov/opt/public_dev/Ado/templates/partials/language_menu.html.ep
#then choose the preferred way to switch languages...
%= include 'partials/language_menu'; # use default language_from => 'route'
%= include 'partials/language_menu', language_from => 'route';
%= include 'partials/language_menu', language_from => 'host';
%= include 'partials/language_menu', language_from => 'param';
%= include 'partials/language_menu', language_from => 'cookie';METHODS
Ado::Plugin::I18n inherits all methods from Ado::Plugin and implements the following new ones.
register
This method is called by $app->plugin. Registers the plugin in Ado application and merges internationalization and localization configuration from $MOJO_HOME/etc/ado.conf with settings defined in $MOJO_HOME/etc/plugins/i18n.conf. Authentication settings defined in ado.conf will overwrite those defined in plugins/i18n.conf. Returns $self.
routes
Returns a list of routes with :language placeholder defined in the plugin configuration. Called in "register". To create your own routes just create etc/plugin/i18n.conf and add them to it. They will replace the default routes.
#default routes including language placeholder.
$app->load_routes($self->routes);
/:language GET,OPTIONS
/:language/:controller GET,OPTIONS
/:language/:controller/:action GET,POST,OPTIONS
/:language/:controller/:action/:id GET,PUT,DELETE,OPTIONSlanguage
This is the underlying subroutine used in around_action hook and c<language> helper.
#Add helpers
$app->helper(language => \&language);around_action
This method is passed as reference to be used as "around_action" in Mojolicious.
# Add hook around_action
$app->hook(around_action => \&around_action);TODO
Create a table with message entries which will be loaded by this plugin. Create user interface to add/edit entries.
SEE ALSO
Locale::Maketext, Ado::Plugin, Ado::Manual::Plugins, Mojolicious::Plugins, Mojolicious::Plugin, "Conditions" in Mojolicious::Guides::Routing
SPONSORS
The original author
AUTHOR
Красимир Беров (Krasimir Berov)
COPYRIGHT AND LICENSE
Copyright 2014 Красимир Беров (Krasimir Berov).
This program is free software, you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License v3 (LGPL-3.0). You may copy, distribute and modify the software provided that modifications are open source. However, software that includes the license may release under a different license.
See http://opensource.org/licenses/lgpl-3.0.html for more information.