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

FreeBSD Manual Pages

  
 
  

home | help
msgcat(n)		     Tcl Bundled Packages		     msgcat(n)

______________________________________________________________________________

NAME
       msgcat -	Tcl message catalog

SYNOPSIS
       package require Tcl 8.5

       package require msgcat 1.5

       ::msgcat::mc src-string ?arg arg	...?

       ::msgcat::mcmax ?src-string src-string ...?

       ::msgcat::mclocale ?newLocale?

       ::msgcat::mcpreferences

       ::msgcat::mcload	dirname

       ::msgcat::mcset locale src-string ?translate-string?

       ::msgcat::mcmset	locale src-trans-list

       ::msgcat::mcflset src-string ?translate-string?			       |

       ::msgcat::mcflmset src-trans-list

       ::msgcat::mcunknown locale src-string ?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       The msgcat package provides a set of functions that can be used to man-
       age multi-lingual user interfaces.  Text	strings	are defined in a "mes-
       sage  catalog" which is independent from	the application, and which can
       be edited or localized without modifying	the application	 source	 code.
       New  languages or locales are provided by adding	a new file to the mes-
       sage catalog.

       Use of the message catalog is optional by any application  or  package,
       but  is	encouraged  if the application or package wishes to be enabled
       for multi-lingual applications.

COMMANDS
       ::msgcat::mc src-string ?arg arg	...?
	      Returns a	translation of src-string according to the user's cur-
	      rent locale.  If additional arguments past src-string are	given,
	      the format command is used to substitute	the  additional	 argu-
	      ments in the translation of src-string.

	      ::msgcat::mc  will  search  the  messages	defined	in the current
	      namespace	for a translation of src-string; if none is found,  it
	      will  search  in	the parent of the current namespace, and so on
	      until it reaches the global namespace.  If no translation	string
	      exists,  ::msgcat::mcunknown  is	called and the string returned
	      from ::msgcat::mcunknown is returned.

	      ::msgcat::mc is the main function	used to	localize  an  applica-
	      tion.   Instead of using an English string directly, an applica-
	      tion can pass the	English	string through	::msgcat::mc  and  use
	      the  result.  If an application is written for a single language
	      in this fashion, then it is easy to add support  for  additional
	      languages	later simply by	defining new message catalog entries.

       ::msgcat::mcmax ?src-string src-string ...?
	      Given several source strings, ::msgcat::mcmax returns the	length
	      of the longest translated	string.	 This is useful	when designing
	      localized	GUIs, which may	require	that all buttons, for example,
	      be a fixed width (which will be the width	of the widest button).

       ::msgcat::mclocale ?newLocale?
	      This function sets the locale to	newLocale.   If	 newLocale  is
	      omitted,	the  current locale is returned, otherwise the current
	      locale is	set to newLocale.  msgcat stores and compares the  lo-
	      cale in a	case-insensitive manner, and returns locales in	lower-
	      case.  The initial locale	is determined by the locale  specified
	      in the user's environment.  See LOCALE SPECIFICATION below for a
	      description of the locale	string format.

       ::msgcat::mcpreferences
	      Returns an ordered list of the locales preferred	by  the	 user,
	      based on the user's language specification.  The list is ordered
	      from most	specific to least preference.	The  list  is  derived
	      from the current locale set in msgcat by ::msgcat::mclocale, and
	      cannot be	set independently.  For	example, if the	current	locale
	      is    en_US_funky,    then    ::msgcat::mcpreferences    returns
	      {en_US_funky en_US en {}}.

       ::msgcat::mcload	dirname
	      Searches the specified directory for files that match  the  lan-
	      guage  specifications  returned by ::msgcat::mcpreferences (note
	      that these are all lowercase), extended by  the  file  extension
	      ".msg".	Each  matching file is read in order, assuming a UTF-8
	      encoding.	 The file contents are then evaluated as a Tcl script.
	      This means that Unicode characters may be	present	in the message
	      file either directly in their UTF-8 encoded form,	or by  use  of
	      the  backslash-u quoting recognized by Tcl evaluation.  The num-
	      ber of message files which matched the  specification  and  were
	      loaded is	returned.

       ::msgcat::mcset locale src-string ?translate-string?
	      Sets  the	 translation for src-string to translate-string	in the
	      specified	locale and the current namespace.  If translate-string
	      is not specified,	src-string is used for both.  The function re-
	      turns translate-string.

       ::msgcat::mcmset	locale src-trans-list
	      Sets the translation for multiple	source strings	in  src-trans-
	      list  in	the  specified locale and the current namespace.  src-
	      trans-list must have an even number of elements and  is  in  the
	      form  {src-string	 translate-string ?src-string translate-string
	      ...?} ::msgcat::mcmset can be significantly faster than multiple
	      invocations  of ::msgcat::mcset. The function returns the	number
	      of translations set.

       ::msgcat::mcflset src-string ?translate-string?
	      Sets the translation for src-string to translate-string  in  the |
	      current namespace	for the	locale implied by the name of the mes- |
	      sage catalog being loaded	via ::msgcat::mcload.	If  translate- |
	      string is	not specified, src-string is used for both.  The func- |
	      tion returns translate-string.

       ::msgcat::mcflmset src-trans-list
	      Sets the translation for multiple	source strings	in  src-trans- |
	      list in the current namespace for	the locale implied by the name |
	      of the message catalog being loaded via  ::msgcat::mcload.  src- |
	      trans-list  must	have  an even number of	elements and is	in the |
	      form {src-string translate-string	 ?src-string  translate-string |
	      ...?} ::msgcat::mcflmset can be significantly faster than	multi- |
	      ple invocations of ::msgcat::mcflset. The	function  returns  the |
	      number of	translations set.

       ::msgcat::mcunknown locale src-string ?arg arg ...?
	      This routine is called by	::msgcat::mc in	the case when a	trans-
	      lation for src-string is not defined in the current locale.  The
	      default action is	to return src-string passed by format if there
	      are any arguments.  This procedure can be	redefined by  the  ap-
	      plication,  for  example	to log error messages for each unknown
	      string.  The ::msgcat::mcunknown procedure  is  invoked  at  the
	      same  stack  context  as	the  call to ::msgcat::mc.  The	return
	      value of ::msgcat::mcunknown is used as the return value for the
	      call to ::msgcat::mc.

LOCALE SPECIFICATION
       The  locale  is specified to msgcat by a	locale string passed to	::msg-
       cat::mclocale.  The locale string consists of a language	code,  an  op-
       tional  country	code, and an optional system-specific code, each sepa-
       rated by	"_".  The country and language codes are  specified  in	 stan-
       dards  ISO-639  and  ISO-3166.	For example, the locale	"en" specifies
       English and "en_US" specifies U.S. English.

       When the	msgcat package is first	loaded,	the locale is initialized  ac-
       cording	 to   the  user's  environment.	  The  variables  env(LC_ALL),
       env(LC_MESSAGES), and env(LANG) are examined in order.	The  first  of
       them to have a non-empty	value is used to determine the initial locale.
       The value is parsed according to	the XPG4 pattern

	      language[_country][.codeset][@modifier]

       to extract its parts.  The initial locale is then set by	calling	::msg-
       cat::mclocale with the argument

	      language[_country][_modifier]

       On  Windows  and	Cygwin,	if none	of those environment variables is set,
       msgcat will attempt to extract locale information  from	the  registry.
       From Windows Vista on, the RFC4747 locale name "lang-script-country-op-
       tions" is transformed to	the locale as "lang_country_script"  (Example:
       sr-Latn-CS  ->  sr_cs_latin). For Windows XP, the language id is	trans-
       formed analoguously (Example: 0c1a -> sr_yu_cyrillic).	If  all	 these
       attempts	 to  discover  an  initial  locale from	the user's environment
       fail, msgcat defaults to	an initial locale of "C".

       When a locale is	specified by the user, a "best match" search  is  per-
       formed  during  string  translation.   For example, if a	user specifies
       en_GB_Funky, the	locales	"en_GB_Funky", "en_GB",	"en" and "" (the empty
       string)	are  searched  in order	until a	matching translation string is
       found.  If no translation string	is available, then ::msgcat::mcunknown
       is called.

NAMESPACES AND MESSAGE CATALOGS
       Strings	stored in the message catalog are stored relative to the name-
       space from which	they were added.  This allows multiple packages	to use
       the  same  strings  without fear	of collisions with other packages.  It
       also allows the source string to	be shorter and	less  prone  to	 typo-
       graphical error.

       For example, executing the code

	      ::msgcat::mcset en hello "hello from ::"
	      namespace	eval foo {
		  ::msgcat::mcset en hello "hello from ::foo"
	      }
	      puts [::msgcat::mc hello]
	      namespace	eval foo {puts [::msgcat::mc hello]}

       will print

	      hello from ::
	      hello from ::foo

       When searching for a translation	of a message, the message catalog will
       search first the	current	namespace, then	 the  parent  of  the  current
       namespace,  and	so on until the	global namespace is reached.  This al-
       lows child namespaces to	"inherit" messages  from  their	 parent	 name-
       space.

       For example, executing (in the "en" locale) the code

	      ::msgcat::mcset en m1 "::	message1"
	      ::msgcat::mcset en m2 "::	message2"
	      ::msgcat::mcset en m3 "::	message3"
	      namespace	eval ::foo {
		  ::msgcat::mcset en m2	"::foo message2"
		  ::msgcat::mcset en m3	"::foo message3"
	      }
	      namespace	eval ::foo::bar	{
		  ::msgcat::mcset en m3	"::foo::bar message3"
	      }
	      namespace	import ::msgcat::mc
	      puts "[mc	m1]; [mc m2]; [mc m3]"
	      namespace	eval ::foo {puts "[mc m1]; [mc m2]; [mc	m3]"}
	      namespace	eval ::foo::bar	{puts "[mc m1];	[mc m2]; [mc m3]"}

       will print

	      :: message1; :: message2;	:: message3
	      :: message1; ::foo message2; ::foo message3
	      :: message1; ::foo message2; ::foo::bar message3

LOCATION AND FORMAT OF MESSAGE FILES
       Message files can be located in any directory, subject to the following
       conditions:

       [1]    All message files	for a package are in the same directory.

       [2]    The message file name is a msgcat	locale specifier  (all	lower-
	      case) followed by	".msg".	 For example:

	      es.msg	-- spanish
	      en_gb.msg	-- United Kingdom English

       Exception:   The	 message  file	for  the  root	locale	""  is	called
       "ROOT.msg".  This exception is made so as not to	cause peculiar	behav-
       ior, such as marking the	message	file as	"hidden" on Unix file systems.

       [3]    The  file	 contains  a  series of	calls to mcflset and mcflmset,
	      setting the necessary  translation  strings  for	the  language,
	      likely  enclosed	in a namespace eval so that all	source strings
	      are tied to the namespace	of the package.	For example,  a	 short
	      es.msg might contain:

	      namespace	eval ::mypackage {
		  ::msgcat::mcflset "Free Beer"	"Cerveza Gratis"
	      }

RECOMMENDED MESSAGE SETUP FOR PACKAGES
       If  a  package  is installed into a subdirectory	of the tcl_pkgPath and
       loaded via package require, the following procedure is recommended.

       [1]    During package installation, create a  subdirectory  msgs	 under
	      your package directory.

       [2]    Copy your	*.msg files into that directory.

       [3]    Add the following	command	to your	package	initialization script:

	      #	load language files, stored in msgs subdirectory
	      ::msgcat::mcload [file join [file	dirname	[info script]] msgs]

POSITIONAL CODES FOR FORMAT AND	SCAN COMMANDS
       It  is  possible	 that  a  message string used as an argument to	format
       might have positionally dependent parameters  that  might  need	to  be
       repositioned.   For example, it might be	syntactically desirable	to re-
       arrange the sentence structure while translating.

	      format "We produced %d units in location %s" $num	$city
	      format "In location %s we	produced %d units" $city $num

       This can	be handled by using the	positional parameters:

	      format "We produced %1\$d	units in location %2\$s" $num $city
	      format "In location %2\$s	we produced %1\$d units" $num $city

       Similarly, positional parameters	can be used with scan to extract  val-
       ues  from  internationalized  strings. Note that	it is not necessary to
       pass the	output of ::msgcat::mc to format directly; by passing the val-
       ues  to substitute in as	arguments, the formatting substitution is done
       directly.

	      msgcat::mc {Produced %1$d	at %2$s} $num $city
	      #	... where that key is mapped to	one of the
	      #	human-oriented versions	by msgcat::mcset

CREDITS
       The message catalog code	was developed by Mark Harrison.

SEE ALSO
       format(n), scan(n), namespace(n), package(n)

KEYWORDS
       internationalization, i18n, localization, l10n, message,	text, transla-
       tion

msgcat				      1.5			     msgcat(n)

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | LOCALE SPECIFICATION | NAMESPACES AND MESSAGE CATALOGS | LOCATION AND FORMAT OF MESSAGE FILES | RECOMMENDED MESSAGE SETUP FOR PACKAGES | POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS | CREDITS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=msgcat.tcl85&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help