gettext: Interface to gettext

1 
1 11.2.1 The Interface
1 --------------------
1 
1    The minimal functionality an interface must have is a) to select a
1 domain the strings are coming from (a single domain for all programs is
1 not reasonable because its construction and maintenance is difficult,
1 perhaps impossible) and b) to access a string in a selected domain.
1 
1    This is principally the description of the ‘gettext’ interface.  It
1 has a global domain which unqualified usages reference.  Of course this
1 domain is selectable by the user.
1 
1      char *textdomain (const char *domain_name);
1 
1    This provides the possibility to change or query the current status
1 of the current global domain of the ‘LC_MESSAGE’ category.  The argument
1 is a null-terminated string, whose characters must be legal in the use
1 in filenames.  If the DOMAIN_NAME argument is ‘NULL’, the function
1 returns the current value.  If no value has been set before, the name of
1 the default domain is returned: _messages_.  Please note that although
1 the return value of ‘textdomain’ is of type ‘char *’ no changing is
1 allowed.  It is also important to know that no checks of the
1 availability are made.  If the name is not available you will see this
1 by the fact that no translations are provided.
1 
1 To use a domain set by ‘textdomain’ the function
1 
1      char *gettext (const char *msgid);
1 
1 is to be used.  This is the simplest reasonable form one can imagine.
1 The translation of the string MSGID is returned if it is available in
1 the current domain.  If it is not available, the argument itself is
1 returned.  If the argument is ‘NULL’ the result is undefined.
1 
1    One thing which should come into mind is that no explicit dependency
1 to the used domain is given.  The current value of the domain is used.
1 If this changes between two executions of the same ‘gettext’ call in the
1 program, both calls reference a different message catalog.
1 
1    For the easiest case, which is normally used in internationalized
1 packages, once at the beginning of execution a call to ‘textdomain’ is
1 issued, setting the domain to a unique name, normally the package name.
1 In the following code all strings which have to be translated are
1 filtered through the gettext function.  That’s all, the package speaks
1 your language.
1