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