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/suche
DESCRIPTION
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 | German
That 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 | German
METHODS
setup ( )
Allows Catalyst::Request to localize the results of calls to uri_with.
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_request ( )
Establishes a reference in the request back to its associated context
object. This is required to enable localization within the uri_with
method of Catalyst::Request.
prepare_path ( )
Delocalizes the requested path.
prepare_parameters ( )
Delocalizes the requested parameter names.
finalize( )
Deletes the request's reference to its associated context object. This
is very important, as it avoids memory leaks.
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
* Catalyst::Plugin::I18N
* Catalyst
AUTHOR
Adam Paynter <adapay@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2006 by Adam Paynter
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.