Apache-Language

 view release on metacpan or  search on metacpan

Language.pm  view on Meta::CPAN

    
#Dumps the language object for debugging purposes.
sub dump {
    my $self = shift;
    $self = tied %$self if tied %$self;
    print "<PRE>";
    print Dumper $self;
    print "</PRE>";
    }

#given an ordered list of knowns languages, returns the best language 
#choice according to the client request
#Called mostly by LanguageHandlers to figure out what language to pick
sub best_lang {
    my ($self,@offered) = @_;
    my ($result, $language);

    $self = tied %$self if tied %$self;
    foreach my $want (@ {$self->{Lang}}) {
        foreach my $offer (@offered) {
            my $similarity = similarity_language_tag($offer, $want);
            if ($similarity){
                return $offer if same_language_tag($offer, $want);
                }

Language.pod  view on Meta::CPAN

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

Language.pod  view on Meta::CPAN

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

Language.pod  view on Meta::CPAN

This is called for each request to know if the datasource changed and should be re-initialized.
It should return true if something is modified and re-initialization is needed.

=item fetch ($data, $cfg, $key, $lang)

This function can be called in 2 ways.  First if there $lang is defined, the LanguageHandler is requested to produce
that exact language version for the key $key. This happends if a user requested a specific language with $lang->{key/lang} or to
find an entry for the default language if everything else failed to produce a value.  It should return undef if unknown.  

Second, if $lang is undefined, this means that the Handler should try to return the best possible match for the current request.
$data->lang will return the list of language the client understands, sorted preferred first.  But since language-tags allow
for variants and dialects, it's now always easy for a module to determine what language it should pick if it knows 'en-us' and 'en' 
and the clients understands 'en-ca' and 'de'.  

=item Everything else

If a call is made to an unknown routine, Apache::Language will try to call it on each Handler in the current
handler stack until someone can deal with that function call.  The call is made with ($data, $cfg, @args) as arguments.
@args being the arguments passed to that function by the calling user.  Remember that to get at the new() arguments,
you just have to do a @args = @{$data->extra_args()};

To simplyfy some things, there is the helper function $data->best_lang described below.

=back

=head2 Helper API Functions

=over

=item $data->best_lang(@avaliable_language)

This is the generic best-language picking routine.  This function given the list of known languages to the
handler, returns the best language based on the client's request.

For example, a simple handler could handle queries like this:

 sub fetch {
    my ($class, $data, $cfg, $key, $lang) = @_;	
    #the language information is kept in the $cfg hash

    #if a specific language is asked for:
    return $cfg->{$key}{$lang} if $lang;  

    #we must choose the right language ourself.
    #(keys % {$cfg->{$key}}) produces the list of languages in wich $key is known     
    my $variant = $data->best_lang(keys % {$cfg->{$key}});
    
    #$variant now holds the best pick for us, or undef if nothing matches..
    return $cfg->{$key}{$variant} if $variant;
    
    #give up
    return undef;     
 }

=back

=head2 Optionnal API Functions (store)

Language/DBI.pm  view on Meta::CPAN

        my @language;
        my $sth;
        
        unless ($variant) {
            $sth = $cfg->{dbh}->prepare("select $cfg->{lang} from ".$cfg->{tablename}." where $cfg->{key}=?") || return undef;
            if ($sth->execute($key)){
            while (my @row = $sth->fetchrow){
                $row[0] =~ s/\s+//;
                push @language, $row[0];
                }
            $variant = $data->best_lang(@language);
            }
            
        }

        return undef unless $variant;
        
        $sth = $cfg->{dbh}->prepare("select $cfg->{value} from ".$cfg->{tablename}." where $cfg->{key}=? and $cfg->{lang}=?") || return undef;
        $sth->execute($key,$variant);
        return $sth->fetchrow;	
}

Language/DBI.pm  view on Meta::CPAN

 PerlSetVar Language::DBI::TableName language [default]
 Language::DBI::TableKey		key 	[column for the key]
 Language::DBI::TableLang		lang	[column for the lang]
 Language::DBI::TableValue 	value [column for the value]
 LanguageHandler Apache::Language::DBI
 </Location>

=head1 DESCRIPTION

This LanguageHandler implements a per-location DBI dictionnary.  It looks-up a given
table for a matching language/key pair and returns the best possible match.

The configurable directives are pretty self-explanatory.

=head1 TODO

Some sort of caching could be done.

=head1 SEE ALSO

perl(1), L<Apache>(3), L<Apache::Language>(3) L<Apache::Language::Constants>(3), and all L<Apache::Language::*>. 

Language/PlainFile.pm  view on Meta::CPAN

sub store {
    my ($class, $data, $cfg, $key, $lang, $value) = @_;
    $cfg->{DATA}{$key}{$lang} = $value;
    return L_OK;
    }

sub fetch {
    my ($class, $data, $cfg, $key, $lang) = @_;	
    return $cfg->{DATA}{$key}{$lang} if $lang;  
    
    my $variant = $data->best_lang(keys % {$cfg->{DATA}{$key}});
    return $cfg->{DATA}{$key}{$variant} if $variant;
    return undef;     
}

sub firstkey {
    my ($class, $data, $cfg) = @_;
    my $a = keys % {$cfg->{DATA}};
    return each % {$cfg->{DATA}};
    }