msgcat man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

msgcat(n)		     Tcl Bundled Packages		     msgcat(n)

______________________________________________________________________________

NAME
       msgcat - Tcl message catalog

SYNOPSIS
       package require Tcl 8.2

       package require msgcat 1.3

       ::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::mcunknown locale src-string
_________________________________________________________________

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
       ``message  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 message 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  application.
       Instead	of  using  an English string directly, an application 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	defin‐
       ing 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
	      locale in a case-insensitive manner, and returns locales in low‐
	      ercase.  The initial locale is determined by the	locale	speci‐
	      fied  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 non-Latin characters may be present in the mes‐
	      sage file either directly in their UTF-8 encoded form, or by use
	      of  the  backslash-u  quoting recognized by Tcl evaluation.  The
	      number 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
	      returns 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::mcunknown locale src-string
	      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.  This procedure  can  be
	      redefined	 by the application, 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
       optional 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
       according  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, if none of those environment variables is set, msgcat will
       attempt to extract locale information from the registry.	 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'',  and  ``en''  are
       searched	 in order until a matching translation string is found.	 If no
       translation string is available, then ::msgcat::unknown is called.

NAMESPACES AND MESSAGE CATALOGS
       Strings stored in the message catalog are stored relative to the names‐
       pace  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
	      mcset en hello "hello from ::"
	      namespace eval foo {mcset en hello "hello from ::foo"}
	      puts [mc hello]
	      namespace eval foo {puts [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
       allows  child namespaces to "inherit" messages from their parent names‐
       pace.

       For example, executing (in the ``en'' locale) the code
	      mcset en m1 ":: message1"
	      mcset en m2 ":: message2"
	      mcset en m3 ":: message3"
	      namespace eval ::foo {
		  mcset en m2 "::foo message2"
		  mcset en m3 "::foo message3"
	      }
	      namespace eval ::foo::bar {
		  mcset en m3 "::foo::bar message3"
	      }
	      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

       [3]    The file contains a series of calls to mcset and mcmset, 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::mcset es "Free Beer!" "Cerveza Gracias!"
	      }

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

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.3			     msgcat(n)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net