NAME
       msgcat - Tcl message catalog

SYNOPSIS
       ::msgcat::mc src-string

       ::msgcat::mclocale ?newLocale?

       ::msgcat::mcpreferences

       ::msgcat::mcload dirname

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

       ::msgcat::mcunknown locale src-string


DESCRIPTION
       The msgcat package provides a set of functions that can be
       used  to  manage  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  pack-
       age 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 current locale.  If additional arguments
              past  src-string  are  given, the format command is
              used to substitute the additional arguments 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 applicaton can pass the English string  through  ::msg-
       cat::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::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.   The  initial  locale  defaults  to the
              locale specified in the  user's  environment.   See
              LOCALE  AND  SUBLOCALE  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 specifica-
              tion.  The list is ordered from  most  specific  to
              least   preference.   If  the  user  has  specified
              LANG=en_US_funky,  this  procedure   would   return
              {en_US_funky en_US en}.

       ::msgcat::mcload dirname
              Searches  the  specified  directory  for files that
              match  the  language  specifications  returned   by
              ::msgcat::mcpreferences.    Each  file  located  is
              sourced.  The file extension is ``.msg''.  The num-
              ber  of  message files which matched the specifica-
              tion 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.   If translate-
              string is not specified,  src-string  is  used  for
              both.  The function returns translate-string.

       ::msgcat::mcunknown locale src-string
              This  routine is called by ::msgcat::mc in the case
              when a translation 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 mes-
              sages for each unknown string.  The ::msgcat::mcun-
              known  procedure  is invoked at the same stack con-
              text as the call to ::msgcat::mc.  The return  vaue
              of  ::msgcat::mcunknown  is used as the return vaue
              for the call to ::msgcat::mc.


LOCALE AND SUBLOCALE SPECIFICATION
       The locale is specified by a locale  string.   The  locale
       string  consists  of  a language code, an optional country
       code, and an optional system-specific code, each separated
       by ``_''.  The country and language codes are specified in
       standards ISO-639 and ISO-3166.  For example,  the  locale
       ``en'' specifies English and
        ``en_US'' specifes  U.S. English.
       The  locale defaults to the value in env(LANG) at the time
       the  msgcat  package  is  loaded.   If  env(LANG)  is  not
       defined, then the locale defaults to ``C''.

       When  a  locale is specified by the user, a ``best match''
       search is performed during string translation.  For  exam-
       ple,   if   a  user  specifies  en_UK_Funky,  the  locales
       ``en_UK_Funky'', ``en_UK'', 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 namespace 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 typographical
       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 namespace.

       For example, executing 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  locale  specifier  fol-
              lowed by ``.msg''.  For example:
              es.msg    -- spanish
              en_UK.msg -- UK English

       [3]    The  file contains a series of calls to mcset, set-
              ting the necessary translation strings for the lan-
              guage. For example:
              ::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 initial-
              ization script:
              # load language files, stored in msgs subdirectory
              ::msgcat::mcload [file join [file dirname [info script]] msgs]


POSTITIONAL 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 values 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, translation
