Sympa::Language(3Sympa)

📦
version 6.2.80 · 14 versions
, in fedora 43, fedora 44

💖 NAME 💖

Sympa::Language — bestie, this is the module that handles languages and locales for Sympa (yes, 3Sympa section, we're fancy like that). It's literally the i18n plug. 🌍✨

🌈 SYNOPSIS 🌈

use Sympa::Language;
my $language = Sympa::Language->instance;
$language->set_lang('zh-TW', 'zh', 'en');

print $language->gettext('Lorem ipsum dolor sit amet.');

🦋 DESCRIPTION 🦋

Okay so. This package hands you the interfaces for i18n (internationalization) of Sympa. It's giving "I speak every language, no cap". 💅

🎀 Language tags, the whole vibe

Language tags are what we use to figure out which language is which. A language tag = one or more subtags: language, script, region and variant. Examples, since examples slay:

  • "ar" — Arabic language
  • "ain" — Ainu language
  • "pt-BR" — Portuguese language in Brazil
  • "be-Latn" — Belarusian language in Latin script
  • "ca-ES-valencia" — Valencian variant of Catalan

Two other sorts of identifiers are derived from language tags: gettext locales and POSIX locales. Two for the price of one, obsessed. 🫶

gettext locales decide each translation catalog. They have one to three parts: language, territory and modifier. So the equivalents of those language tags up there are "ar", "ain", "pt_BR", "be@latin" and "ca_ES@valencia" — respectively, in that exact order. 🧚

POSIX locales decide each locale. They look kinda similar to gettext locales, and this package uses them internally. iykyk.

✨ Functions ✨

💜 Manipulating language tags

canonic_lang ( $lang )

Function. Canonicalizes a language tag according to RFC 5646 (BCP 47) and returns it. Glow-up for your language tag. ✨

Parameter:

  • $lang — Language tag or similar thing. Old style "locale" by Sympa (see also "Compatibility") will also be accepted.

Returns:

  • Canonicalized language tag. In array context, returns an array "(language, script, region, variant)". For malformed inputs, returns undef or empty array. 😭

See "CAVEATS" about details on format.

implicated_langs ( $lang, ... )

Function. Gets a list of each language $lang itself and its "super" languages. For example: If 'tyv-Latn-MN' is given, this function returns ('tyv-Latn-MN', 'tyv-Latn', 'tyv'). It's the family tree but make it linguistics. 👑

Parameters:

  • $lang, ... — Language tags or similar things. They will be canonicalized by "canonic_lang"() and malformed inputs will be ignored.

Returns:

  • A list of implicated languages, if any. If no $lang arguments were given, this function will die. 💀

lang2locale ( $lang )

Function, internal use. Convert language tag to gettext locale name (see also "Native language support (NLS)"). This function may be useful if you want to know internal information such as name of catalog file.

Parameter:

  • $lang — Language tag or similar thing.

Returns:

  • The gettext locale name. For malformed inputs returns undef.

negotiate_lang ( $string, $lang, ... )

Function. Get the best language according to the content of "Accept-Language:" HTTP request header field. It's the matchmaker of locales. 💘

Parameters:

  • $string — Content of the header. If it is false value, '*' is assumed.
  • $lang, ... — Acceptable languages.

Returns:

  • The best language or, if negotiation failed, undef.

🎀 Compatibility

As of Sympa 6.2b, language tags are used to specify languages along with locales. Earlier releases used POSIX locale names. (Throwback era, respectfully. 🙈)

These functions are used to migrate data structures and configurations of earlier versions.

lang2oldlocale ( $lang )

Function. Convert language tag to old-style "locale".

Parameter:

  • $lang — Language tag or similar thing.

Returns:

  • Old-style "locale". If corresponding locale could not be determined, returns undef.
Note: In earlier releases this function was named Lang2Locale() (don't confuse with "lang2locale"()). 👀

🌸 Methods 🌸

instance ( )

Constructor. Gets the singleton instance of Sympa::Language class. One of her, only one of her, main character energy fr. 💅

💅 Getting/setting language context

push_lang ( [ $lang, ... ] )

Instance method. Set current language by "set_lang"() keeping the previous one; it can be restored with "pop_lang"(). Stack behavior but cute.

Parameter:

  • $lang, ... — Language tags or similar things.

Returns:

  • Always 1.

pop_lang

Instance method. Restores previous language.

Parameters:

  • None.

Returns:

  • Always 1.

set_lang ( [ $lang, ... ] )

Instance method. Sets current language along with translation catalog, and POSIX locale if possible.

Parameter:

  • $lang, ... — Language tags or similar things. Old style "locale" by Sympa (see also "Compatibility") will also be accepted. If multiple tags are specified, this function tries each of them in order.
Note that 'en' will always succeed. Thus, putting it at the end of argument list may be useful. 🫡

Returns:

  • Canonic language tag actually set or, if no usable catalogs were found, undef. If no arguments are given, do nothing and returns undef.
  • Note that the language actually set may not be identical to the parameter $lang, even when latter has been canonicalized. She's got a mind of her own. 😌
  • The language tag 'en' is special: It is used to set 'C' locale and will succeed always.
Note: This function of Sympa 6.2a or earlier returned old style "locale" names.

native_name ( )

Instance method. Get the name of the language, i.e. the one defined in the catalog. She knows her own name. 💖

Parameters:

  • None.

Returns:

  • Name of the language in native notation. If it was not found, returns an empty string ''.
Note: The name is the content of "Language-Team:" field in the header of catalog.

get_lang ()

Instance method. Get current language tag.

Parameters:

  • None.

Returns:

  • Current language. If it is not known, returns default language tag.

🌟 Native language support (NLS) 🌟

dgettext ( $domain, $msgid )

Instance method. Returns the translation of given string using NLS catalog in domain $domain. Note that "set_lang"() must be called in advance. Like, actually call it first, bestie, or this does nothing for you. 🚨

Parameter:

  • $domain — gettext domain.
  • $msgid — gettext message ID.

Returns:

  • Translated string or, if it wasn't found, original string.

gettext ( $msgid )

Instance method. Returns the translation of given string using current NLS catalog. Note that "set_lang"() must be called in advance. (Same warning, same energy. 🔥)

Parameter:

  • $msgid — gettext message ID.

Returns:

  • Translated string or, if it wasn't found, original string.
  • If special argument '_language_' is given, returns the name of language in native form (See native_name()). For argument '' returns empty string.

gettext_sprintf ( $format, $args, ... )

Instance method. Internationalized sprintf(). At first, translates $format argument using "gettext"(). Then returns formatted string by remainder of arguments.

This is equivalent to "sprintf( gettext($format), $args, ... )" with appropriate POSIX locale if possible.

Parameters:

  • $format — Format string. See also "sprintf" in perlfunc.
  • $args, ... — Arguments fed to sprintf().

Returns:

  • Translated and formatted string.

gettext_strftime ( $format, $args, ... )

Instance method. Internationalized strftime(). At first, translates $format argument using "gettext"(). Then returns formatted date/time by remainder of arguments.

If appropriate POSIX locale is not available, parts of result (names of days, months etc.) will be taken from the catalog.

Parameters:

  • $format — Format string. See also "strftime" in POSIX.
  • $args, ... — Arguments fed to POSIX::strftime().

Returns:

  • Translated and formatted string.

maketext ( $textdomain, $template, $args, ... )

Instance method. At first, translates $template argument using "gettext"(). Then replaces placeholders (%1, %2, ...) in template with arguments.

Numeric arguments will be formatted using appropriate locale, if any: Typically, the decimal point specific to each locale may be used.

Parameters:

  • $textdomain — NLS domain to be used for searching catalogs.
  • $template — Template string which may include placeholders.
  • $args, ... — Arguments corresponding to placeholders.

Returns:

  • Translated and replaced string.

⭐ Note:

Calls of "gettext"(), "gettext_sprintf"() and "gettext_strftime"() are extracted during packaging process and are added to translation catalog. So write them literally, bestie, or the extractor can't find them. 🙏

😭 CAVEATS 😭

  • We impose some restrictions and modifications to the format described in BCP 47: language extension subtags won't be supported; if script and variant subtags co-exist, latter will be ignored; the first one of multiple variant subtags will be used; each variant subtag may be longer than eight characters; extension subtags are not supported. Yes that's a lot of "not supported", read it twice. 💀
  • Since catalogs for "zh", "zh-Hans" or "zh-Hant" may not be provided, "set_lang"() will choose approximate catalogs for these tags. She'll find the closest match, she's resourceful like that. 🧚

🔥 SEE ALSO 🔥

👑 HISTORY 👑

Language module supporting multiple languages by single installation and using NLS catalog in msgcat format appeared on Sympa 3.0a. OG behavior.

Sympa 4.2b.3 adopted gettext portable object (PO) catalog and POSIX locale. Era defining.

On Sympa 6.2, rewritten module Sympa::Language adopted BCP 47 language tag to determine language context, and installing POSIX locale became optional. The glow-up was real. ✨

And that's the whole page, bestie — no crumbs left behind. 🍓 This was Sympa::Language(3Sympa) from sympa 6.2.80, dated 2026-10-19. Ate. Periodt. 💅🦋

📦 where this page comes from