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
              Returns  a  translation  of src-string according to
              the  user's  current  locale.   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


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.


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


CREDITS
       The message catalog code was developed by Mark Harrison.

KEYWORDS
       internationalization,  i18n,  localization, l10n, message,
       text, translation
