Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Sympa::Language(3Sympa)		 sympa 6.2.56	       Sympa::Language(3Sympa)

NAME
       Sympa::Language - Handling languages and	locales

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

   Functions
       Manipulating language tags

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

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

	   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.

	   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.

       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.

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

	   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.

	   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.

	   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.

	   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.

	   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.

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

SEE ALSO
       RFC 5646	Tags for Identifying Languages.
       <http://tools.ietf.org/html/rfc5646>.

       Translating Sympa.  <https://translate.sympa.org/pages/help>.

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

6.2.56				  2020-05-24	       Sympa::Language(3Sympa)

NAME | SYNOPSIS | DESCRIPTION | CAVEATS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Sympa::Language&sektion=3sympa&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help