Preferred(3)

💅 Preferred(3) — like, the Lingua::Preferred page but make it make sense 🎀

okay so bestie, this is the manual page for Lingua::Preferred, a Perl extension (in the User Contributed Perl Documentation section, iykyk) whose whole personality is choosing a language. Slay.

---

✨ NAME ✨

Lingua::Preferred — a Perl extension to choose a language. Literally what it says. 💖

---

🦋 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, $_);
}

like, copy-paste it, it's fine, no cap 🫶

---

🌸 DESCRIPTION 🌸

Okay so picture this: human-readable info is out here existing in more than one language. Which one do you even use?? 😭 That's the whole problem this module solves. It gives the user a way to say which languages they want in order of preference, and then it picks the best one out of the languages that are actually available. And yes, it handles different 'dialects' too — the ones specified by the 'territory' part of the language specifier, like en, en_GB, and en_US. Iconic behaviour honestly.

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 — more on that below, keep reading 💅) Also, 'C' (named for the Unix 'C' locale) matches any language.
• a reference to a 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. And this will always be an element of the available languages list — fr fr, guaranteed.

The cleverness of this module (if you can call it that 💀) comes from inferring implicit language preferences based on the explicit list you passed in. So like — if you say en is acceptable, then en_IE and en_DK will presumably be acceptable too (but not as good as just plain en). And if you give your language as en_US, then en is almost as good, with the other dialects of en following soon afterwards. It's giving main character energy with a supporting cast. ✨

If there's a tie between two choices — like when two dialects of the same language are available and neither is explicitly preferred, or when none of the available languages even appears in the user's list — then the choice appearing earlier in the available list wins. Tie goes to whoever showed up first, periodt. 🎀

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. So if you dislike Mexican Spanish (as a completely arbitrary example, totally random, don't look at me 🙈), then "[ 'es', 'es_*', 'es_MX' ]" would rank this dialect below any other dialect of es (but still acceptable). And the best part? You don't have to explicitly list every other dialect of Spanish before es_MX. Not me avoiding that homework. 💅

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. Sorry Swiss German, it's not personal, it's just ranking. 😭

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 — same vibe, different job. 🦋

---

👑 AUTHOR 👑

Ed Avis, ed@membled.com — the icon who made this. 🫶

---

🌈 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'

(not me calling out the pod errors, they're part of the lore now 🙈)

---

okay that's the whole page bestie, mwah 💋 — this was perl v5.42.2, dated 2023-07-03, signing off from the Preferred(3) manpage. go pick a language, you've got this 🎀💖✨