.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sympa::Language 3Sympa"
.TH Sympa::Language 3Sympa "2020-12-30" "6.2.58" "sympa 6.2.58"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sympa::Language \- Handling languages and locales
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Sympa::Language;
\&  my $language = Sympa::Language\->instance;
\&  $language\->set_lang(\*(Aqzh\-TW\*(Aq, \*(Aqzh\*(Aq, \*(Aqen\*(Aq);
\&  
\&  print $language\->gettext(\*(AqLorem ipsum dolor sit amet.\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides interfaces for i18n (internationalization) of Sympa.
.PP
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.
.IP "\(bu" 4
\&\f(CW\*(C`ar\*(C'\fR \- Arabic language
.IP "\(bu" 4
\&\f(CW\*(C`ain\*(C'\fR \- Ainu language
.IP "\(bu" 4
\&\f(CW\*(C`pt\-BR\*(C'\fR \- Portuguese language in Brazil
.IP "\(bu" 4
\&\f(CW\*(C`be\-Latn\*(C'\fR \- Belarusian language in Latin script
.IP "\(bu" 4
\&\f(CW\*(C`ca\-ES\-valencia\*(C'\fR \- Valencian variant of Catalan
.PP
Other two sorts of identifiers are derived from language tags:
gettext locales and \s-1POSIX\s0 locales.
.PP
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 \f(CW\*(C`ar\*(C'\fR, \f(CW\*(C`ain\*(C'\fR,
\&\f(CW\*(C`pt_BR\*(C'\fR, \f(CW\*(C`be@latin\*(C'\fR and \f(CW\*(C`ca_ES@valencia\*(C'\fR, respectively.
.PP
The \s-1POSIX\s0 locales determine each \fIlocale\fR.  They have similar forms to
gettext locales and are used by this package internally.
.SS "Functions"
.IX Subsection "Functions"
\fIManipulating language tags\fR
.IX Subsection "Manipulating language tags"
.ie n .IP "canonic_lang ( $lang )" 4
.el .IP "canonic_lang ( \f(CW$lang\fR )" 4
.IX Item "canonic_lang ( $lang )"
\&\fIFunction\fR.
Canonicalizes language tag according to \s-1RFC 5646\s0 (\s-1BCP 47\s0) and returns it.
.Sp
Parameter:
.RS 4
.ie n .IP "$lang" 4
.el .IP "\f(CW$lang\fR" 4
.IX Item "$lang"
Language tag or similar thing.
Old style \*(L"locale\*(R" by Sympa (see also \*(L"Compatibility\*(R") will also be
accepted.
.RE
.RS 4
.Sp
Returns:
.Sp
Canonicalized language tag.
In array context, returns an array
\&\f(CW\*(C`(\f(CIlanguage\f(CW, \f(CIscript\f(CW, \f(CIregion\f(CW, \f(CIvariant\f(CW)\*(C'\fR.
For malformed inputs, returns \f(CW\*(C`undef\*(C'\fR or empty array.
.Sp
See \*(L"\s-1CAVEATS\*(R"\s0 about details on format.
.RE
.ie n .IP "implicated_langs ( $lang, ... )" 4
.el .IP "implicated_langs ( \f(CW$lang\fR, ... )" 4
.IX Item "implicated_langs ( $lang, ... )"
\&\fIFunction\fR.
Gets a list of each language \f(CW$lang\fR itself and its \*(L"super\*(R" languages.
For example:
If \f(CW\*(Aqtyv\-Latn\-MN\*(Aq\fR is given, this function returns
\&\f(CW\*(C`(\*(Aqtyv\-Latn\-MN\*(Aq, \*(Aqtyv\-Latn\*(Aq, \*(Aqtyv\*(Aq)\*(C'\fR.
.Sp
Parameters:
.RS 4
.ie n .IP "$lang, ..." 4
.el .IP "\f(CW$lang\fR, ..." 4
.IX Item "$lang, ..."
Language tags or similar things.
They will be canonicalized by \*(L"canonic_lang\*(R"()
and malformed inputs will be ignored.
.RE
.RS 4
.Sp
Returns:
.Sp
A list of implicated languages, if any.
If no \f(CW$lang\fR arguments were given, this function will die.
.RE
.ie n .IP "lang2locale ( $lang )" 4
.el .IP "lang2locale ( \f(CW$lang\fR )" 4
.IX Item "lang2locale ( $lang )"
\&\fIFunction\fR, \fIinternal use\fR.
Convert language tag to gettext locale name
(see also \*(L"Native language support (\s-1NLS\s0)\*(R").
This function may be useful if you want to know internal information such as
name of catalog file.
.Sp
Parameter:
.RS 4
.ie n .IP "$lang" 4
.el .IP "\f(CW$lang\fR" 4
.IX Item "$lang"
Language tag or similar thing.
.RE
.RS 4
.Sp
Returns:
.Sp
The gettext locale name.
For malformed inputs returns \f(CW\*(C`undef\*(C'\fR.
.RE
.ie n .IP "negotiate_lang ( $string, $lang, ... )" 4
.el .IP "negotiate_lang ( \f(CW$string\fR, \f(CW$lang\fR, ... )" 4
.IX Item "negotiate_lang ( $string, $lang, ... )"
\&\fIFunction\fR.
Get the best language according to the content of \f(CW\*(C`Accept\-Language:\*(C'\fR \s-1HTTP\s0
request header field.
.Sp
Parameters:
.RS 4
.ie n .IP "$string" 4
.el .IP "\f(CW$string\fR" 4
.IX Item "$string"
Content of the header.  If it is false value, \f(CW\*(Aq*\*(Aq\fR is assumed.
.ie n .IP "$lang, ..." 4
.el .IP "\f(CW$lang\fR, ..." 4
.IX Item "$lang, ..."
Acceptable languages.
.RE
.RS 4
.Sp
Returns:
.Sp
The best language or, if negotiation failed, \f(CW\*(C`undef\*(C'\fR.
.RE
.PP
\fICompatibility\fR
.IX Subsection "Compatibility"
.PP
As of Sympa 6.2b, language tags are used to specify languages along with
locales.  Earlier releases used \s-1POSIX\s0 locale names.
.PP
These functions are used to migrate data structures and configurations of
earlier versions.
.ie n .IP "lang2oldlocale ( $lang )" 4
.el .IP "lang2oldlocale ( \f(CW$lang\fR )" 4
.IX Item "lang2oldlocale ( $lang )"
\&\fIFunction\fR.
Convert language tag to old-style \*(L"locale\*(R".
.Sp
Parameter:
.RS 4
.ie n .IP "$lang" 4
.el .IP "\f(CW$lang\fR" 4
.IX Item "$lang"
Language tag or similar thing.
.RE
.RS 4
.Sp
Returns:
.Sp
Old-style \*(L"locale\*(R".
If corresponding locale could not be determined, returns \f(CW\*(C`undef\*(C'\fR.
.Sp
Note:
In earlier releases this function was named \fBLang2Locale()\fR
(don't confuse with \*(L"lang2locale\*(R"()).
.RE
.SS "Methods"
.IX Subsection "Methods"
.IP "instance ( )" 4
.IX Item "instance ( )"
\&\fIConstructor\fR.
Gets the singleton instance of Sympa::Language class.
.PP
\fIGetting/setting language context\fR
.IX Subsection "Getting/setting language context"
.ie n .IP "push_lang ( [ $lang, ... ] )" 4
.el .IP "push_lang ( [ \f(CW$lang\fR, ... ] )" 4
.IX Item "push_lang ( [ $lang, ... ] )"
\&\fIInstance method\fR.
Set current language by \*(L"set_lang\*(R"() keeping the previous one;
it can be restored with \*(L"pop_lang\*(R"().
.Sp
Parameter:
.RS 4
.ie n .IP "$lang, ..." 4
.el .IP "\f(CW$lang\fR, ..." 4
.IX Item "$lang, ..."
Language tags or similar things.
.RE
.RS 4
.Sp
Returns:
.Sp
Always \f(CW1\fR.
.RE
.IP "pop_lang" 4
.IX Item "pop_lang"
\&\fIInstance method\fR.
Restores previous language.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
Always \f(CW1\fR.
.ie n .IP "set_lang ( [ $lang, ... ] )" 4
.el .IP "set_lang ( [ \f(CW$lang\fR, ... ] )" 4
.IX Item "set_lang ( [ $lang, ... ] )"
\&\fIInstance method\fR.
Sets current language along with translation catalog,
and \s-1POSIX\s0 locale if possible.
.Sp
Parameter:
.RS 4
.ie n .IP "$lang, ..." 4
.el .IP "\f(CW$lang\fR, ..." 4
.IX Item "$lang, ..."
Language tags or similar things.
Old style \*(L"locale\*(R" by Sympa (see also \*(L"Compatibility\*(R") will also be
accepted.
If multiple tags are specified, this function tries each of them in order.
.Sp
Note that \f(CW\*(Aqen\*(Aq\fR will always succeed.  Thus, putting it at the end of
argument list may be useful.
.RE
.RS 4
.Sp
Returns:
.Sp
Canonic language tag actually set or, if no usable catalogs were found,
\&\f(CW\*(C`undef\*(C'\fR.  If no arguments are given, do nothing and returns \f(CW\*(C`undef\*(C'\fR.
.Sp
Note that the language actually set may not be identical to the parameter
\&\f(CW$lang\fR, even when latter has been canonicalized.
.Sp
The language tag \f(CW\*(Aqen\*(Aq\fR is special:
It is used to set \f(CW\*(AqC\*(Aq\fR locale and will succeed always.
.Sp
Note:
This function of Sympa 6.2a or earlier returned old style \*(L"locale\*(R" names.
.RE
.IP "native_name ( )" 4
.IX Item "native_name ( )"
\&\fIInstance method\fR.
Get the name of the language, i.e. the one defined in the catalog.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
Name of the language in native notation.
If it was not found, returns an empty string \f(CW\*(Aq\*(Aq\fR.
.Sp
Note:
The name is the content of \f(CW\*(C`Language\-Team:\*(C'\fR field in the header of catalog.
.IP "get_lang ()" 4
.IX Item "get_lang ()"
\&\fIInstance method\fR.
Get current language tag.
.Sp
Parameters:
.Sp
None.
.Sp
Returns:
.Sp
Current language.
If it is not known, returns default language tag.
.PP
\fINative language support (\s-1NLS\s0)\fR
.IX Subsection "Native language support (NLS)"
.ie n .IP "dgettext ( $domain, $msgid )" 4
.el .IP "dgettext ( \f(CW$domain\fR, \f(CW$msgid\fR )" 4
.IX Item "dgettext ( $domain, $msgid )"
\&\fIInstance method\fR.
Returns the translation of given string using \s-1NLS\s0 catalog in domain \f(CW$domain\fR.
Note that \*(L"set_lang\*(R"() must be called in advance.
.Sp
Parameter:
.RS 4
.ie n .IP "$domain" 4
.el .IP "\f(CW$domain\fR" 4
.IX Item "$domain"
gettext domain.
.ie n .IP "$msgid" 4
.el .IP "\f(CW$msgid\fR" 4
.IX Item "$msgid"
gettext message \s-1ID.\s0
.RE
.RS 4
.Sp
Returns:
.Sp
Translated string or, if it wasn't found, original string.
.RE
.ie n .IP "gettext ( $msgid )" 4
.el .IP "gettext ( \f(CW$msgid\fR )" 4
.IX Item "gettext ( $msgid )"
\&\fIInstance method\fR.
Returns the translation of given string using current \s-1NLS\s0 catalog.
Note that \*(L"set_lang\*(R"() must be called in advance.
.Sp
Parameter:
.RS 4
.ie n .IP "$msgid" 4
.el .IP "\f(CW$msgid\fR" 4
.IX Item "$msgid"
gettext message \s-1ID.\s0
.RE
.RS 4
.Sp
Returns:
.Sp
Translated string or, if it wasn't found, original string.
.Sp
If special argument \f(CW\*(Aq_language_\*(Aq\fR is given,
returns the name of language in native form (See native_name()).
For argument \f(CW\*(Aq\*(Aq\fR returns empty string.
.RE
.ie n .IP "gettext_sprintf ( $format, $args, ... )" 4
.el .IP "gettext_sprintf ( \f(CW$format\fR, \f(CW$args\fR, ... )" 4
.IX Item "gettext_sprintf ( $format, $args, ... )"
\&\fIInstance method\fR.
Internationalized sprintf().
At first, translates \f(CW$format\fR argument using \*(L"gettext\*(R"().
Then returns formatted string by remainder of arguments.
.Sp
This is equivalent to \f(CW\*(C`sprintf( gettext($format), $args, ... )\*(C'\fR
with appropriate \s-1POSIX\s0 locale if possible.
.Sp
Parameters:
.RS 4
.ie n .IP "$format" 4
.el .IP "\f(CW$format\fR" 4
.IX Item "$format"
Format string.
See also \*(L"sprintf\*(R" in perlfunc.
.ie n .IP "$args, ..." 4
.el .IP "\f(CW$args\fR, ..." 4
.IX Item "$args, ..."
Arguments fed to \fBsprintf()\fR.
.RE
.RS 4
.Sp
Returns:
.Sp
Translated and formatted string.
.RE
.ie n .IP "gettext_strftime ( $format, $args, ... )" 4
.el .IP "gettext_strftime ( \f(CW$format\fR, \f(CW$args\fR, ... )" 4
.IX Item "gettext_strftime ( $format, $args, ... )"
\&\fIInstance method\fR.
Internationalized strftime().
At first, translates \f(CW$format\fR argument using \*(L"gettext\*(R"().
Then returns formatted date/time by remainder of arguments.
.Sp
If appropriate \s-1POSIX\s0 locale is not available, parts of result (names of days,
months etc.) will be taken from the catalog.
.Sp
Parameters:
.RS 4
.ie n .IP "$format" 4
.el .IP "\f(CW$format\fR" 4
.IX Item "$format"
Format string.
See also \*(L"strftime\*(R" in \s-1POSIX\s0.
.ie n .IP "$args, ..." 4
.el .IP "\f(CW$args\fR, ..." 4
.IX Item "$args, ..."
Arguments fed to \fBPOSIX::strftime()\fR.
.RE
.RS 4
.Sp
Returns:
.Sp
Translated and formatted string.
.RE
.ie n .IP "maketext ( $textdomain, $template, $args, ... )" 4
.el .IP "maketext ( \f(CW$textdomain\fR, \f(CW$template\fR, \f(CW$args\fR, ... )" 4
.IX Item "maketext ( $textdomain, $template, $args, ... )"
\&\fIInstance method\fR.
At first, translates \f(CW$template\fR argument using \*(L"gettext\*(R"().
Then replaces placeholders (\f(CW%1\fR, \f(CW%2\fR, ...) in template with arguments.
.Sp
Numeric arguments will be formatted using appropriate locale, if any:
Typically, the decimal point specific to each locale may be used.
.Sp
Parameters:
.RS 4
.ie n .IP "$textdomain" 4
.el .IP "\f(CW$textdomain\fR" 4
.IX Item "$textdomain"
\&\s-1NLS\s0 domain to be used for searching catalogs.
.ie n .IP "$template" 4
.el .IP "\f(CW$template\fR" 4
.IX Item "$template"
Template string which may include placeholders.
.ie n .IP "$args, ..." 4
.el .IP "\f(CW$args\fR, ..." 4
.IX Item "$args, ..."
Arguments corresponding to placeholders.
.RE
.RS 4
.Sp
Returns:
.Sp
Translated and replaced string.
.RE
.PP
\&\fBNote\fR:
.PP
Calls of \*(L"gettext\*(R"(), \*(L"gettext_sprintf\*(R"() and \*(L"gettext_strftime\*(R"() are 
extracted during packaging process and are added to translation catalog.
.SH "CAVEATS"
.IX Header "CAVEATS"
.IP "\(bu" 4
We impose some restrictions and modifications to the format described in
\&\s-1BCP 47:\s0
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.
.IP "\(bu" 4
Since catalogs for \f(CW\*(C`zh\*(C'\fR, \f(CW\*(C`zh\-Hans\*(C'\fR or \f(CW\*(C`zh\-Hant\*(C'\fR may not be provided,
\&\*(L"set_lang\*(R"() will choose approximate catalogs for these tags.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC 5646\s0 \fITags for Identifying Languages\fR.
<http://tools.ietf.org/html/rfc5646>.
.PP
\&\fITranslating Sympa\fR.
<https://translate.sympa.org/pages/help>.
.SH "HISTORY"
.IX Header "HISTORY"
Language module supporting multiple languages by single installation
and using \s-1NLS\s0 catalog in msgcat format appeared on Sympa 3.0a.
.PP
Sympa 4.2b.3 adopted gettext portable object (\s-1PO\s0) catalog and \s-1POSIX\s0 locale.
.PP
On Sympa 6.2, rewritten module Sympa::Language adopted \s-1BCP 47\s0 language tag
to determine language context, and installing \s-1POSIX\s0 locale became optional.