NAME

Para::Frame::L10N - framework for localization

DESCRIPTION

Objects of this class represent a specific language preference. That preference will be extracted from the request. Each request should create it's own object.

A request can change its language preference by methods on this object, or by creating another object with diffrent preferences.

Exportable functions are /loc and /locescape.

loc

  loc( $phrase )

  loc( $phrase, @args )

Calls Locale::Maketext/maketext with the given arguments using the request language handler set by Para::Frame::Request/set_language.

This is an exportable function.

locescape

  locescape( $phrase )

Escapes special symbols in the string that is going to be parsed by MakeText /loc. This escapes [, ], and ~.

Returns: A scalar string

set

  $class->set()

  $class->set( \@langcodes )

  $class->set( $langcode )

  $class->set( $accet_language_header_string )

This sets and returns the language handler in the context of the Request. It is called via Para::Frame::Request/set_language.

If this is a client request and no params are given, the language priority defaults to the query param lang or the cookie lang or the environment variable HTTP_ACCEPT_LANGUAGE in turn.

get_handle

  $class->get_handle( @langcodes )

Extends Locale::Metatext/get_handle to work for one lexicon in Para::Frame::Site/appbase (or Para::Frame::Site/appfmly) and then to fall back on the paraframe lexicons.

If you want more than two lexicons in the chain you have to implement that yourself by extending /get_handle even more.

This extensions also works in the case there there is no site lexicon.

This works by setting the attribute fallback to a paraframe lexicon and teling Locale::Maketext/fail_with to use /fallback_maketext.

fallback_maketext

  $lh->fallback_maketext( $phrase )

  $lh->fallback_maketext( $phrase, @args )

Calls maketext with the fallback language handler. /get_handle sets this to the one retrieved by /Locale::Maketext/get_handle called from Para::Frame::L10N.

compute

  $lh->compute( $value, \$phrase )

  $lh->compute( $value, \$phrase, @args )

The code for this is directly taken from Locale::Maketext/maketext for handling execution of the translation found.

If you prefere to create your own maketext method, you can use this to tie in to the Locale::Maketext framework.

The $value is that returned by the internal _compile method in Locale::Maketext. $phrase should ge biven as a scalar ref of the text to translate, used for fallback and error handling if $value fails. See Locale::Maketext/maketext.

This example reimplements maketext and retrieves the translation from a SQL translation table, storing the compiled values in a %TRANSLATION hash:

    sub maketext
    {
        my( $lh, $phrase ) = (shift, shift );
        my $req = $Para::Frame::REQ;

        return "" unless length($phrase);

        # Retrieves the translation from my database

        my @alts = $req->language->alternatives;
        my( $rec, $value );
        foreach my $langcode ( @alts )
        {
            unless( $value = $TRANSLATION{$phrase}{$langcode} )
    	    {
    	        $rec ||= $My::dbix->select_possible_record(
                                   'from tr where c=?',$phrase) || {};
    	        if( defined $rec->{$langcode} and length $rec->{$langcode} )
    	        {
                    # Compiles the translation value
    		    $value = $TRANSLATION{$phrase}{$langcode}
                           = $lh->_compile($rec->{$langcode});
    		    last;
    	        }
    	        next;
    	    }
    	    last;
        }
        return $lh->compute();
    }

    # Return the computed value

    return $lh->compute($value, \$phrase, @_);

preferred

  $lh->preferred()

  $lh->preferred( $lang1, $lang2, ... )

Returns the language form the list that the user preferes. $langX is the language code, like sv or en.

The list will always be restircted to the languages supported by the site, ie $req->site->languages. The parameters should only be used to restrict the choises futher.

Default

The first language in the list of languages supported by the application.

Example

  [% SWITCH lang %]
  [% CASE 'sv' %]
     <p>Valkommen ska ni vara!</p>
  [% CASE %]
     <p>Welcome, poor thing.</p>
  [% END %]

alternatives

  $lh->alternatives

Returns a ref to a list of language code strings. For example ['en']. This is a prioritized list of languages that the sithe handles and that the client prefere.

code

  $lh->code

Returnes the first language alternative from /alternatives as a string of two characters.

set_headers

  $lh->set_headers()

Sets the headers based on the language used for the request