view release on metacpan or  search on metacpan

Language.pod  view on Meta::CPAN

=head1 NAME

Apache::Language - Perl transparent language support for Apache modules and mod_perl scripts

=head1 SYNOPSIS

  In YourModule.pm:
  
  sub handler {
  my $r = shift;
  use Apache::Language;
  my $lang = Apache::Language->new($extra_args);
  #$lang is now a hash ref that will automacigally pick the right language
  
  print $lang->{'Error01'} if exists $lang->{'Error01'};
  
  foreach ( keys %$lang ){
    print "$_ is " . $lang->{$_};
    }
  
  [...]
  }

=head1 DESCRIPTION

The goal of this module is to provide a simple way for mod_perl module writers
to include support for multiple language requests.

This is version 0.03, and it's a complete rewrite from the ground-up of the 
previous release.  It's still backward-compatible with the other releases, but
now it's much more advanced.

An Apache::Language object acts like a language-aware hash.  It stores key/language/values
triplets. Using the Accept-Language: field sent by the web-client, it can pick the best
fit language for that specific client.  It's usage is transparent and should prove 
to be quite convenient (and hopefully, efficient).

The method used to store/fetch information is now completely modular and will allow
easy creation of new storage methods thru a simple API (see the API section).

=head2 BASIC USAGE EXAMPLE

This section will describe the easiest way to start using Apache::Language.

Apache::Language is used to create a hash that will contain key/language/value triplets.  Say you are
building a module that prints a few error messages, but since your users speak 3 different languages, you'd
like your module to be nice to them and print the messages in their native language.

For this approach to work, a few things are needed.  First, the client software (Netscape/IE/lynx, etc.) should
send an Accept-Language: header telling the webserver what languages it's user understands.  This might sound simple, but
as a web-surfer, did you set that language setting in your browser?  Most likely, you didn't.  So the first step is to 
correctly configure your browser and try to make sure your users/visitors will have done the same, or they might not
get what you want them to read.

Secondly, you must store the messages you want to display in each avaliable languages.  For this example, we will use the
default LanguageHandler Apache::Language::PlainFile that ships with this distribution.  To do that, suppose your module
is named Apache::MyModule and it's stored in a file named MyModule.pm.  You will only need to edit a file named MyModule.dic
in the same place your module is stored.  The format of that file is : (for more information see
L<Apache::Language::PlainFile>(3)).

 error01:en

 Error Message 01

 error01:fr

 Message d'erreur 01

 error02:en

 Error Message 02

Once that file contains your error messages, you're all set.  Just add this to the top of your module:

 use Apache::Language
 my $lang = Apache::Language::new($extra_args)

Then $lang will be a language-enabled hash reference that you can use like this:

 print $lang->{error01}

That line will print your error message 01 in the best language for the client that your module served. Of course, there
are a lot more things you can do with Apache::Language.  All these features are explained below.

=head1 DETAILLED USAGE

The key to using Apache::Language is to understand the the data retrieving/storing is now done in a manner similar to mod_perl
content handlers.  That's why I called them Language Handlers.  A language handler is a perl module that is specialized in
storing/fetching key/language/values triplets.

Apache::Language simply manages those modules and makes interaction with other modules painless.  For every request, Apache::Language
maintains a stack of the LanguageHandlers configured for that request's location.  Asking each of them in order to try
finding a value for the requested key that would satisfy the client acceptable languages.

That way you can have a number of language handlers, one looking up in a system-wide dictionnary, one looking up in a module-specific
dictionnary and one looking up a RDBM.  Each of them would be queried until an acceptable response is found.  This makes maintaining
language definitions pretty versatile and configurable.

With this package is shipped 2 basic LanguageHandlers: L<Apache::Language::PlainFile> and L<Apache::Language::DBI>.  Check out
their respective man pages for more specific information.  And more of those LanguageHandlers will be shipped in future versions
and if you need a specific language handling module, simply write your own.  Read the API section for more information about
writing your own LanguageHandlers and check the 2 mentionned above, they are nice examples.

=head1 CONFIGURATION DIRECTIVES

There are a some configurations directives you can use to customize how Apache::Language handles requests.

=over

=item LanguageHandler

This is the main directive.  It sets the language handlers for a specific location.  It's usage is like IndexOptions.  Meaning
it supports +/- notations.  

With a list of handlers without any +/- signs it simply sets the handler stack for the current location to those.

With a list of handlers all with +/- signs, it merges them with the parent configuration: