1Preferred(3)          User Contributed Perl Documentation         Preferred(3)
2
3
4

NAME

6       Lingua::Preferred - Perl extension to choose a language
7

SYNOPSIS

9         use Lingua::Preferred qw(which_lang acceptable_lang);
10         my @wanted = qw(en de fr it de_CH);
11         my @available = qw(fr it de);
12
13         my $which = which_lang(\@wanted, \@available);
14         print "language $which is the best of those available\n";
15
16         foreach (qw(en_US fr nl de_DE)) {
17             print "language $_ is acceptable\n"
18               if acceptable_lang(\@wanted, $_);
19         }
20

DESCRIPTION

22       Often human-readable information is available in more than one
23       language.  Which should you use?  This module provides a way for the
24       user to specify possible languages in order of preference, and then to
25       pick the best language of those available.  Different 'dialects' given
26       by the 'territory' part of the language specifier (such as en, en_GB,
27       and en_US) are also supported.
28
29       The routine which_lang() picks the best language from a list of
30       alternatives.  The arguments are:
31
32       •   a reference to a list of preferred languages (first is best).
33           Here, a language is a string like 'en' or 'fr_CA'.  ('fr_*' can
34           also be given - see below.)  'C' (named for the Unix 'C' locale)
35           matches any language.
36
37       •   a reference to non-empty list of available languages.  Here, a
38           language can be like 'en', 'en_CA', or "undef" meaning 'unknown'.
39
40       The return code is which language to use.  This will always be an
41       element of the available languages list.
42
43       The cleverness of this module (if you can call it that) comes from
44       inferring implicit language preferences based on the explicit list
45       passed in.  For example, if you say that en is acceptable, then en_IE
46       and en_DK will presumably be acceptable too (but not as good as just
47       plain en).  If you give your language as en_US, then en is almost as
48       good, with the other dialects of en following soon afterwards.
49
50       If there is a tie between two choices, as when two dialects of the same
51       language are available and neither is explicitly preferred, or when
52       none of the available languages appears in the user's list, then the
53       choice appearing earlier in the available list is preferred.
54
55       Sometimes, the automatic inferring of related dialects is not what you
56       want, because a language dialect may be very different to the 'main'
57       language, for example Swiss German or some forms of English.  For this
58       case, the special form 'XX_*' is available. If you dislike Mexican
59       Spanish (as a completely arbitrary example), then "[ 'es', 'es_*',
60       'es_MX' ]" would rank this dialect below any other dialect of es (but
61       still acceptable).  You don't have to explicitly list every other
62       dialect of Spanish before es_MX.
63
64       So for example, supposing @avail contains the languages available:
65
66       •   You know English and prefer US English:
67
68               $which = which_lang([ 'en_US' ], \@avail);
69
70       •   You know English and German, German/Germany is preferred:
71
72               $which = which_lang([ 'en', 'de_DE' ], \@avail);
73
74       •   You know English and German, but preferably not Swiss German:
75
76               $which = which_lang([ 'en', 'de', 'de_*', 'de_CH' ], \@avail);
77
78           Here any dialect of German (eg de_DE, de_AT) is preferable to
79           de_CH.
80
81           Whereas which_lang() picks the best language from a list of
82           alternatives, acceptable_lang() answers whether a single language
83           is included (explicitly or implicitly) in the list of wanted
84           languages.  It adds the implicit dialects in the same way.
85

AUTHOR

87       Ed Avis, ed@membled.com
88

SEE ALSO

90       perl(1).
91

POD ERRORS

93       Hey! The above document had some coding errors, which are explained
94       below:
95
96       Around line 258:
97           You forgot a '=back' before '=head1'
98
99
100
101perl v5.36.0                      2023-01-20                      Preferred(3)
Impressum