view release on metacpan or  search on metacpan

lib/Ado/Plugin/I18n.pm  view on Meta::CPAN

                controller => 'Default',
                action     => 'index'
            }
        },
        {   route  => '/:language/:controller/:action/:id',
            via    => [qw(GET PUT DELETE OPTIONS)],
            params => {
                $$config{language_param} => qr/(?:$l)/,
                controller               => qr/[\w-]{3,}/,
                action                   => qr/\w{3,}/,
                id                       => qr/\d+/
            },
            to => {

                #Ado::Control::Default
                controller => 'Default',
                action     => 'form'
            }
        },
    ];
}


sub register {
    my ($self, $app, $config) = shift->initialise(@_);

    #Make sure we have all we need from config files.
    $config->{default_language} ||= 'en';

    #Supported languages by this system
    $config->{languages} ||= ['en', 'de', 'bg'];

    # Language will be guessed from one of these places in the order below.
    # Specify/narrow your preferences in etc/plugins/i18n.conf.
    $config->{language_from_route}   //= 1;
    $config->{language_from_host}    //= 1;
    $config->{language_from_param}   //= 1;
    $config->{language_from_cookie}  //= 1;
    $config->{language_from_headers} //= 1;
    $config->{language_param}        //= 'language';

    #Allow other namespaces too
    $config->{namespace} ||= 'Ado::I18n';

    my $e = Mojo::Loader::load_class($config->{namespace});
    $app->log->error(qq{Loading "$config->{namespace}" failed: $e}) if $e;

    # Defaults for $c->stash so templates without controllers can be used
    $app->defaults(language => '', language_from => '');

    #Add helpers
    $app->helper(language => \&language);
    $app->helper(l        => \&_maketext);

    #default routes including language placeholder.
    $app->load_routes($self->routes);

    # Add hook around_action
    $app->hook(around_action => \&around_action);

    #Add to classes used for finding templates in DATA sections
    push @{$app->renderer->classes}, __PACKAGE__;

    #make plugin configuration available for later in the app
    $app->config(__PACKAGE__, $config);
    return $self;
}

#Mojolicious::around_action hook.
sub around_action {
    my ($next, $c, $action, $last_step) = @_;
    $c->language();
    return $next->();
}

# Sets *once* and/or returns the current language - a controller attribute
sub language {
    my ($c, $language) = @_;
    state $config  = $c->app->config(__PACKAGE__);
    state $l_param = $$config{language_param};
    my $stash = $c->stash;

    #language('fr') should be used in very
    #rare cases since it is called in around_action
    if ($language) {
        $stash->{i18n} =
          $$config{namespace}->get_handle($language, $c, $config);
        $c->debug("explicitly set by developer.");
        return $stash->{$l_param} = $language;
    }

    #already set from route or called in an action as: $c->language()
    if ($stash->{$l_param}) {
        $stash->{i18n}
          ||= $$config{namespace}->get_handle($stash->{$l_param}, $c, $config);
        $c->debug("already set in \$stash->{$l_param}:");
        return $stash->{$l_param};
    }

    #bg.example.com
    if ($$config{language_from_host}
        && (my ($l) = $c->req->headers->host =~ /^(\w{2})\./))
    {
        $stash->{i18n} =
          $$config{namespace}->get_handle($l, $c, $config);
        $stash->{language_from} = 'host';
        return $stash->{$l_param} = $l;
    }

    #?language=de
    if ($$config{language_from_param}
        && (my $l = ($c->param($l_param) // '')))
    {
        $stash->{$l_param} = $l;
        $stash->{language_from} = 'param';
    }

    if (  !$stash->{$l_param}
        && $$config{language_from_cookie}
        && ($language = $c->cookie($l_param)))
    {

lib/Ado/Plugin/I18n.pm  view on Meta::CPAN

L<Ado::Plugin::I18n> localizes your application and site.
It automatically detects the current UserAgent language preferences
and selects the best fit from the supported by the application languages.
The current language is detected and set in L<Mojolicious/around_action> hook.
Various methods for setting the language are supported.

=head1 OPTIONS

The following options can be set in C<etc/ado.conf> or in C<etc/plugins/i18n.conf>.
You have to create first C<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.3

Just be careful not to try to set the language in one request using two different
methods eg. C</bg/controller/action?language=de>.


=head2 default_language

The default value is C<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 L</namespace>.

=head2 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,OPTIONS

The language will be detected from current routes eg. C</bg/news/read/1234>
and put into the stash. Default value is 1.

=head2 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  C<language_from_route>
or do not construct routes containing languages (eg. C<fr.example.com/en>).
Default value is 1.

=head2 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 C<fr.example.com?language=de>
or even C<fr.example.com/bg?language=de>. The result is usually not what you want.
Default value is 1.

=head2 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.

=head2 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.

=head2 language_param

    #language_param=> 'l'
    current language is <%= $l %>
    Cookie: l=bg;
    #language_param=> 'lang'