Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SYMPA::LANGUAGE (3)

.ds Aq ’


Sympa::Language - Handling languages and locales



  use Sympa::Language;
  my $language = Sympa::Language->instance;
  $language->set_lang(zh-TW, zh, en);
  print $language->gettext(Lorem ipsum dolor sit amet.);


This package provides interfaces for i18n (internationalization) of Sympa.

The language tags are used to determine each language. A language tag consists of one or more subtags: language, script, region and variant. Below are some examples.
o ar - Arabic language
o ain - Ainu language
o pt-BR - Portuguese language in Brazil
o be-Latn - Belarusian language in Latin script
o ca-ES-valencia - Valencian variant of Catalan
Other two sorts of identifiers are derived from language tags: gettext locales and POSIX locales.

The gettext locales determine each translation catalog. It consists of one to three parts: language, territory and modifier. For example, their equivalents of language tags above are ar, ain, pt_BR, be@latin and ca_ES@valencia, respectively.

The POSIX locales determine each locale. They have similar forms to gettext locales and are used by this package internally.


Manipulating language tags
canonic_lang ( $lang ) Function. Canonicalizes language tag according to RFC 5646 (BCP 47) and returns it.

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


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).

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


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.

$lang Language tag or similar thing.


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.

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


The best language or, if negotiation failed, undef.

As of Sympa 6.2b, language tags are used to specify languages along with locales. Earlier releases used POSIX locale names.
These functions are used to migrate data structures and configurations of earlier versions.
lang2oldlocale ( $lang ) Function. Convert language tag to old-style locale.

$lang Language tag or similar thing.


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()).


instance ( ) Constructor. Gets the singleton instance of Sympa::Language class.
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().

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


Always 1.

pop_lang Instance method. Restores previous language.




Always 1.

set_lang ( [ $lang, ... ] ) Instance method. Sets current language along with translation catalog, and POSIX locale if possible.

$lang, ... Language tags or similer things. Old style locale by Sympa (see also Compatibility) will also be accepted. If multiple tags are specified, this function trys each of them in order.

Note that en will always succeed. Thus, putting it at the end of argument list may be useful.


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.

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, ie the one defined in the catalog.




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.




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.

$domain gettext domain.
$msgid gettext message ID.


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.

$msgid gettext message ID.


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.

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


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.

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


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.

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


Translated and replaced string.


Calls of gettext(), gettext_sprintf() and gettext_strftime() are extracted during packaging process and are added to translation catalog.


o 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.
o Since catalogs for zh, zh-Hans or zh-Hant may not be provided, set_lang() will choose approximate catalogs for these tags.


RFC 5646 Tags for Identifying Languages. <>.

Translating Sympa. <>.


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

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

On Sympa 6.2, rewritten module Sympa::Language adopted BCP 47 language tag to determine language context, and installing POSIX locale became optional.

Search for    or go to Top of page |  Section 3 |  Main Index

6.2.14 SYMPA::LANGUAGE (3Sympa) 2016-02-23

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.