Ado::Plugin::I18n - Internationalization and localization for Ado
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;
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.
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.
etc/ado.conf
etc/plugins/i18n.conf
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.3
Just be careful not to try to set the language in one request using two different methods eg. /bg/controller/action?language=de.
/bg/controller/action?language=de
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".
en
{ 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,OPTIONS
The language will be detected from current routes eg. /bg/news/read/1234 and put into the stash. Default value is 1.
/bg/news/read/1234
{ 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_route
fr.example.com/en
{ 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.
fr.example.com?language=de
fr.example.com/bg?language=de
{ 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 => 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=> '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".
language_from_param
language_from_cookie
$c->stash
The namespace used for language classes. Default value is Ado::I18n. You rarely will want to change this.
Ado::Plugin::I18n exports the following helpers for use in Ado::Control methods and templates.
Wrapper for "maketext" in Locale::Maketext.
$c->render(text => $c->l('hello', $c->user->name)); <%= l('hello', user->name) %>
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.
templates/добре/ок.html.ep
% language('bg');
Ado::Plugin::I18n contains one embeded template.
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';
Ado::Plugin::I18n inherits all methods from Ado::Plugin and implements the following new ones.
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.
$app->plugin
$MOJO_HOME/etc/ado.conf
$MOJO_HOME/etc/plugins/i18n.conf
ado.conf
plugins/i18n.conf
$self
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.
:language
etc/plugin/i18n.conf
#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,OPTIONS
This is the underlying subroutine used in around_action hook and c<language> helper.
around_action
#Add helpers $app->helper(language => \&language);
This method is passed as reference to be used as "around_action" in Mojolicious.
# Add hook around_action $app->hook(around_action => \&around_action);
Create a table with message entries which will be loaded by this plugin. Create user interface to add/edit entries.
Locale::Maketext, Ado::Plugin, Ado::Manual::Plugins, Mojolicious::Plugins, Mojolicious::Plugin, "Conditions" in Mojolicious::Guides::Routing
The original author
Красимир Беров (Krasimir Berov)
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.
To install Ado, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ado
CPAN shell
perl -MCPAN -e shell install Ado
For more information on module installation, please visit the detailed CPAN module installation guide.