NAME

       Lingua::Preferred - Perl extension to choose a language

SYNOPSIS

         use Lingua::Preferred qw(which_lang acceptable_lang);
         my @wanted = qw(en de fr it de_CH);
         my @available = qw(fr it de);

         my $which = which_lang(\@wanted, \@available);
         print "language $which is the best of those available\n";

         foreach (qw(en_US fr nl de_DE)) {
             print "language $_ is acceptable\n"
               if acceptable_lang(\@wanted, $_);
         }

DESCRIPTION

       Often human-readable information is available in more than one language.  Which should you
       use?  This module provides a way for the user to specify possible languages in order of
       preference, and then to pick the best language of those available.  Different 'dialects'
       given by the 'territory' part of the language specifier (such as en, en_GB, and en_US) are
       also supported.

       The routine "which_lang()" picks the best language from a list of alternatives.  The
       arguments are:

       •   a reference to a list of preferred languages (first is best).  Here, a language is a
           string like 'en' or 'fr_CA'.  ('fr_*' can also be given - see below.)  'C' (named for
           the Unix 'C' locale) matches any language.

       •   a reference to non-empty list of available languages.  Here, a language can be like
           'en', 'en_CA', or "undef" meaning 'unknown'.

       The return code is which language to use.  This will always be an element of the available
       languages list.

       The cleverness of this module (if you can call it that) comes from inferring implicit
       language preferences based on the explicit list passed in.  For example, if you say that
       en is acceptable, then en_IE and en_DK will presumably be acceptable too (but not as good
       as just plain en).  If you give your language as en_US, then en is almost as good, with
       the other dialects of en following soon afterwards.

       If there is a tie between two choices, as when two dialects of the same language are
       available and neither is explicitly preferred, or when none of the available languages
       appears in the user's list, then the choice appearing earlier in the available list is
       preferred.

       Sometimes, the automatic inferring of related dialects is not what you want, because a
       language dialect may be very different to the 'main' language, for example Swiss German or
       some forms of English.  For this case, the special form 'XX_*' is available. If you
       dislike Mexican Spanish (as a completely arbitrary example), then "[ 'es', 'es_*', 'es_MX'
       ]" would rank this dialect below any other dialect of es (but still acceptable).  You
       don't have to explicitly list every other dialect of Spanish before es_MX.

       So for example, supposing @avail contains the languages available:

       •   You know English and prefer US English:

               $which = which_lang([ 'en_US' ], \@avail);

       •   You know English and German, German/Germany is preferred:

               $which = which_lang([ 'en', 'de_DE' ], \@avail);

       •   You know English and German, but preferably not Swiss German:

               $which = which_lang([ 'en', 'de', 'de_*', 'de_CH' ], \@avail);

           Here any dialect of German (eg de_DE, de_AT) is preferable to de_CH.

           Whereas "which_lang()" picks the best language from a list of alternatives,
           "acceptable_lang()" answers whether a single language is included (explicitly or
           implicitly) in the list of wanted languages.  It adds the implicit dialects in the
           same way.

AUTHOR

       Ed Avis, ed@membled.com

SEE ALSO

       perl(1).

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 258:
           You forgot a '=back' before '=head1'