NAME
Catalyst::Plugin::I18N::Request - A plugin for localizing/delocalizing paths and parameters.
SYNOPSIS
package My::App;
use Catalyst qw( ConfigLoader Static::Simple I18N I18N::Request );
1;
...
package My::App::Controller::Root;
use base qw( Catalyst::Controller );
sub search : Private {
my ($self, $c) = @_;
my $searchTerms = $c->req->param('searchTerms');
# yadda, yadda, yadda...
}
...
French:
Requested as:
GET /recherche?terms_de_recherche=Pirates HTTP/1.0
Accept-Language: fr
Dispatched as:
GET /search?searchTerms=Pirates HTTP/1.0
Accept-Language: fr
$c->uri_for('/search'):
http://localhost/recherche
German:
Requested as:
GET /suche?searchTerms=Pirates HTTP/1.0
Accept-Language: de
Dispatched as:
GET /search?searchTerms=Pirates HTTP/1.0
Accept-Language: de
$c->uri_for('/search'):
http://localhost/sucheDESCRIPTION
This plugin is designed to work alongside Catalyst::Plugin::I18N in order to provide localization / delocalization of request paths and request parameter names.
DELOCALIZATION
Delocalization occurs when a request is first received, before any dispatching takes place. Delocalization assumes that there may exist paths or parameter names within the request which do not correlate to actual names used within the application itself. When functioning properly, this plugin will allow users to activate an action called 'search' using:
'recherche' (French requests)
'suche' (German requests)
etc... This relies on the localize method provided to the application by Catalyst::Plugin::I18N. For the above examples to work, the following localizations must occur:
Key | Localized text | Language
==========================================================
PATH_delocalize_recherche | search | French
PATH_delocalize_suche | search | GermanThat is, $c->localize('PATH_delocalize_recherche') must return 'search'. A very similar behaviour applies to parameter names within the query string. The keys for these delocalizations begin with 'PARAMETER_delocalize_' instead of 'PATH_delocalize_'.
LOCALIZATION
Localization involves taking paths and parameter names and replacing them with values which make more sense to users speaking the requested language. In the above example, 'search' may not look intuitive to German users. Out of the box, this plugin allows you to localize these values transparently via the standard $c->uri_for and $c->request->uri_with methods which are already standard features of the Catalyst framework.
Like delocalization, this functionality depends upon the $c->localize method. However, PATH_delocalize_ is replaced with PATH_localize and PARAMETER_delocalize_ is replaced with PARAMETER_localize_.
Key | Localized text | Language
==========================================================
PATH_localize_search | recherche | French
PATH_localize_search | suche | GermanMETHODS
setup ( )
Allows Catalyst::Request to localize the results of calls to uri_with.
prepare ( )
Overrides Catalyst's prepare method to push the context object to the request object.
uri_for ( $path [, @args ] [, \%query_values ] )
Calls the native uri_for, but proceeds to localize the resulting path and query values.
localize_uri ( $uri )
Localizes a URI using the current context.
localize_path ( $path )
Localizes all components of the provided path.
delocalize_path ( $path )
Delocalizes all components of the provided path.
transform_parameters ( \%parameters, $transformer )
Transforms the given parameter names using the given transformer. The transformer may be one of the following:
A CODE reference which accepts the context object as the first argument and a parameter name as the second argument.
The name of a particular accessor that can be called on the context object, accepting a parameter name as the argument.
localize_parameters ( \%parameters )
Localizes the keys within a hash of parameters.
delocalize_parameters ( \%parameters )
Delocalizes the keys within a hash of parameters.
prepare_path ( )
Delocalizes the requested path.
prepare_parameters ( )
Delocalizes the requested parameter names.
localize_path_component ( $delocalized )
Localizes a component of a path.
delocalize_path_component ( $localized )
Delocalizes a component of a path.
localize_parameter_name ( $delocalized )
Localizes a parameter name.
delocalize_parameter_name ( $localized )
Delocalizes a parameter name.
SEE ALSO
AUTHORS
Adam Paynter <adapay@cpan.org>
Brian Cassidy <bricas@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2006-2012 by Adam Paynter, Brian Cassidy
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.