I18N::...nguage(3pm)

💖 I18N::...nguage 💖 (that's the 3pm chapter of the User Contributed Perl Documentation, bestie)

okay so. you know how the internet is like, everyone, everywhere, all at once? 🌍 this module is the little matchmaker that figures out which language your server should actually speak back. it's Perl, it's from the I18N:: family, and it's serving multilingual realness. slay. 💅

---

✨ NAME ✨

I18N::AcceptLanguage — matches language preference to available languages 🫶

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe in one go:

use I18N::AcceptLanguage;

my $supportedLanguages = [( 'en-us', 'fr' )];

my $acceptor = I18N::AcceptLanguage->new();
my $language = $acceptor->accepts($ENV{HTTP_ACCEPT_LANGUAGE},
                                  $supportedLanguages);

---

🦋 DESCRIPTION 🦋

I18N::AcceptLanguage takes what the client wants and matches it against what the server has, following the rules laid out in RFC 2616, section 14.4: HTTP/1.1 - Header Field Definitions - Accept-Language.

that's it. that's the whole job. matchmaker behavior only. 😌

---

👑 PUBLIC METHODS 👑

accepts( CLIENT_PREFERENCES, SUPPORTED_LANGUAGES )

gives you back the highest priority common language between client and server. 💞

if there's genuinely no common language found, it returns the defaultLanguage instead. and if defaultLanuage isn't set either — yes, that typo is theirs, not mine 🙈 — you get back an empty string.

this method wants exactly two arguments, no more no less:

CLIENT_PREFERENCES

a string in the exact same format defined in RFC 2616, which we are quoting here verbatim:

1#( ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) [ "'" "q" "=" qvalue ] )

some examples so you can see it in the wild:

da, en-gb;q=0.8, en;q=0.7

en-us, ja, *

SUPPORTED_LANGUAGES

a reference to a list of language ranges that your server actually supports. 💖

---

new( [ OPTIONS ] )

returns a shiny new I18N::AcceptLanguage object. ✨ it takes these key/value pair options:

• debug — a boolean, so 0 or 1. set it to 1 and debug messages get printed to STDOUT. defaults to 0.
• defaultLanguage — a string that's your server's default language choice. defaults to an empty string.
• strict — a boolean, 0 or 1. when it's 1, the software strictly conforms to the protocol specification. when it's 0, it does a secondary, aggressive language match regardless of country — so like, a client asking for only en-gb will get back en-us if the server doesn't accept en-gb or en but does accept en-us. in that non-strict case, the last matching language in the supported languages list will be chosen. defaults to 1.

ngl, know which mode you're in before you ship it. strict is the default for a reason. 👀

---

🙈 PRIVATE METHODS 🙈

these are the lil internal helpers. get/set energy all the way down.

• debug( [ BOOLEAN ] ) — a get/set method that returns the value of debug, set by the optional method argument.
• defaultLanguage( [ LANGUAGE ] ) — a get/set method that returns the value of defaultLanguage, set by the optional method argument.
• strict( [ BOOLEAN ] ) — a get/set method that returns the value of strict, set by the optional method argument.

---

🎀 NOTES 🎀

Case Sensitivity

matches are done in a case-insensitive manner, but the results are case-sensitive to the value found in the SUPPORTED_LANGUAGES list.

so it'll find EN-US and en-us as the same thing, but it hands you back whatever casing your own list used. iconic honestly. ✨

---

🌈 AVAILABILITY 🌈

this module is available on CPAN worldwide 🌍 and requires perl version 5.6.1 or higher to be installed. yes bestie, it's ancient and it still eats. 💀

---

💜 AUTHORS 💜

Christian Gilmore <cag@us.ibm.com>

---

🔥 SEE ALSO 🔥

RFC 2616

---

🍓 COPYRIGHT 🍓

Copyright (C) 2003, 2004 International Business Machines Corporation and others. All Rights Reserved.

this module is free software; you can redistribute it and/or modify it under the terms of the IBM Public License. 🫶

---

and that's the whole page, babe. 💖 this one's documented for perl v5.36.0, dated 2022-10-13 — go forth and let your server speak every language it can, no cap. 👑🌈✨