(libc.info.gz) Locating gettext catalog

Info Catalog (libc.info.gz) Translation with gettext (libc.info.gz) Message catalogs with gettext (libc.info.gz) Advanced gettext functions
 
 8.2.1.2 How to determine which catalog to be used
 .................................................
 
 The functions to retrieve the translations for a given message have a
 remarkable simple interface.  But to provide the user of the program
 still the opportunity to select exactly the translation s/he wants and
 also to provide the programmer the possibility to influence the way to
 locate the search for catalogs files there is a quite complicated
 underlying mechanism which controls all this.  The code is complicated
 the use is easy.
 
    Basically we have two different tasks to perform which can also be
 performed by the 'catgets' functions:
 
   1. Locate the set of message catalogs.  There are a number of files
      for different languages and which all belong to the package.
      Usually they are all stored in the filesystem below a certain
      directory.
 
      There can be arbitrary many packages installed and they can follow
      different guidelines for the placement of their files.
 
   2. Relative to the location specified by the package the actual
      translation files must be searched, based on the wishes of the
      user.  I.e., for each language the user selects the program should
      be able to locate the appropriate file.
 
    This is the functionality required by the specifications for
 'gettext' and this is also what the 'catgets' functions are able to do.
 But there are some problems unresolved:
 
    * The language to be used can be specified in several different ways.
      There is no generally accepted standard for this and the user
      always expects the program understand what s/he means.  E.g., to
      select the German translation one could write 'de', 'german', or
      'deutsch' and the program should always react the same.
 
    * Sometimes the specification of the user is too detailed.  If s/he,
      e.g., specifies 'de_DE.ISO-8859-1' which means German, spoken in
      Germany, coded using the ISO 8859-1 character set there is the
      possibility that a message catalog matching this exactly is not
      available.  But there could be a catalog matching 'de' and if the
      character set used on the machine is always ISO 8859-1 there is no
      reason why this later message catalog should not be used.  (We call
      this "message inheritance".)
 
    * If a catalog for a wanted language is not available it is not
      always the second best choice to fall back on the language of the
      developer and simply not translate any message.  Instead a user
      might be better able to read the messages in another language and
      so the user of the program should be able to define a precedence
      order of languages.
 
    We can divide the configuration actions in two parts: the one is
 performed by the programmer, the other by the user.  We will start with
 the functions the programmer can use since the user configuration will
 be based on this.
 
    As the functions described in the last sections already mention
 separate sets of messages can be selected by a "domain name".  This is a
 simple string which should be unique for each program part with uses a
 separate domain.  It is possible to use in one program arbitrary many
 domains at the same time.  E.g., the GNU C Library itself uses a domain
 named 'libc' while the program using the C Library could use a domain
 named 'foo'.  The important point is that at any time exactly one domain
 is active.  This is controlled with the following function.
 
  -- Function: char * textdomain (const char *DOMAINNAME)
      Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
       POSIX Safety Concepts.
 
      The 'textdomain' function sets the default domain, which is used in
      all future 'gettext' calls, to DOMAINNAME.  Please note that
      'dgettext' and 'dcgettext' calls are not influenced if the
      DOMAINNAME parameter of these functions is not the null pointer.
 
      Before the first call to 'textdomain' the default domain is
      'messages'.  This is the name specified in the specification of the
      'gettext' API. This name is as good as any other name.  No program
      should ever really use a domain with this name since this can only
      lead to problems.
 
      The function returns the value which is from now on taken as the
      default domain.  If the system went out of memory the returned
      value is 'NULL' and the global variable ERRNO is set to 'ENOMEM'.
      Despite the return value type being 'char *' the return string must
      not be changed.  It is allocated internally by the 'textdomain'
      function.
 
      If the DOMAINNAME parameter is the null pointer no new default
      domain is set.  Instead the currently selected default domain is
      returned.
 
      If the DOMAINNAME parameter is the empty string the default domain
      is reset to its initial value, the domain with the name 'messages'.
      This possibility is questionable to use since the domain 'messages'
      really never should be used.
 
  -- Function: char * bindtextdomain (const char *DOMAINNAME, const char
           *DIRNAME)
      Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | 
      POSIX Safety Concepts.
 
      The 'bindtextdomain' function can be used to specify the directory
      which contains the message catalogs for domain DOMAINNAME for the
      different languages.  To be correct, this is the directory where
      the hierarchy of directories is expected.  Details are explained
      below.
 
      For the programmer it is important to note that the translations
      which come with the program have be placed in a directory hierarchy
      starting at, say, '/foo/bar'.  Then the program should make a
      'bindtextdomain' call to bind the domain for the current program to
      this directory.  So it is made sure the catalogs are found.  A
      correctly running program does not depend on the user setting an
      environment variable.
 
      The 'bindtextdomain' function can be used several times and if the
      DOMAINNAME argument is different the previously bound domains will
      not be overwritten.
 
      If the program which wish to use 'bindtextdomain' at some point of
      time use the 'chdir' function to change the current working
      directory it is important that the DIRNAME strings ought to be an
      absolute pathname.  Otherwise the addressed directory might vary
      with the time.
 
      If the DIRNAME parameter is the null pointer 'bindtextdomain'
      returns the currently selected directory for the domain with the
      name DOMAINNAME.
 
      The 'bindtextdomain' function returns a pointer to a string
      containing the name of the selected directory name.  The string is
      allocated internally in the function and must not be changed by the
      user.  If the system went out of core during the execution of
      'bindtextdomain' the return value is 'NULL' and the global variable
      ERRNO is set accordingly.
 
Info Catalog (libc.info.gz) Translation with gettext (libc.info.gz) Message catalogs with gettext (libc.info.gz) Advanced gettext functions
automatically generated by info2html