| <html lang="en"> |
| <head> |
| <title>Locating gettext catalog - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Message-catalogs-with-gettext.html#Message-catalogs-with-gettext" title="Message catalogs with gettext"> |
| <link rel="prev" href="Translation-with-gettext.html#Translation-with-gettext" title="Translation with gettext"> |
| <link rel="next" href="Advanced-gettext-functions.html#Advanced-gettext-functions" title="Advanced gettext functions"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Locating-gettext-catalog"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Advanced-gettext-functions.html#Advanced-gettext-functions">Advanced gettext functions</a>, |
| Previous: <a rel="previous" accesskey="p" href="Translation-with-gettext.html#Translation-with-gettext">Translation with gettext</a>, |
| Up: <a rel="up" accesskey="u" href="Message-catalogs-with-gettext.html#Message-catalogs-with-gettext">Message catalogs with gettext</a> |
| <hr> |
| </div> |
| |
| <h5 class="subsubsection">8.2.1.2 How to determine which catalog to be used</h5> |
| |
| <p>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. |
| |
| <p>Basically we have two different tasks to perform which can also be |
| performed by the <code>catgets</code> functions: |
| |
| <ol type=1 start=1> |
| <li>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. |
| |
| <p>There can be arbitrary many packages installed and they can follow |
| different guidelines for the placement of their files. |
| |
| <li>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. |
| </ol> |
| |
| <p>This is the functionality required by the specifications for |
| <code>gettext</code> and this is also what the <code>catgets</code> functions are |
| able to do. But there are some problems unresolved: |
| |
| <ul> |
| <li>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 <code>de</code>, <code>german</code>, or |
| <code>deutsch</code> and the program should always react the same. |
| |
| <li>Sometimes the specification of the user is too detailed. If s/he, e.g., |
| specifies <code>de_DE.ISO-8859-1</code> which means German, spoken in Germany, |
| coded using the ISO 8859-1<!-- /@w --> character set there is the possibility |
| that a message catalog matching this exactly is not available. But |
| there could be a catalog matching <code>de</code> and if the character set |
| used on the machine is always ISO 8859-1<!-- /@w --> there is no reason why this |
| later message catalog should not be used. (We call this <dfn>message |
| inheritance</dfn>.) |
| |
| <li>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 an precedence order of languages. |
| </ul> |
| |
| <p>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. |
| |
| <p>As the functions described in the last sections already mention separate |
| sets of messages can be selected by a <dfn>domain name</dfn>. 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 <code>libc</code> while the program using the C Library could use a |
| domain named <code>foo</code>. The important point is that at any time |
| exactly one domain is active. This is controlled with the following |
| function. |
| |
| <!-- libintl.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: char * <b>textdomain</b> (<var>const char *domainname</var>)<var><a name="index-textdomain-811"></a></var><br> |
| <blockquote><p>The <code>textdomain</code> function sets the default domain, which is used in |
| all future <code>gettext</code> calls, to <var>domainname</var>. Please note that |
| <code>dgettext</code> and <code>dcgettext</code> calls are not influenced if the |
| <var>domainname</var> parameter of these functions is not the null pointer. |
| |
| <p>Before the first call to <code>textdomain</code> the default domain is |
| <code>messages</code>. This is the name specified in the specification of |
| the <code>gettext</code> 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. |
| |
| <p>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 |
| <code>NULL</code> and the global variable <var>errno</var> is set to <code>ENOMEM</code>. |
| Despite the return value type being <code>char *</code> the return string must |
| not be changed. It is allocated internally by the <code>textdomain</code> |
| function. |
| |
| <p>If the <var>domainname</var> parameter is the null pointer no new default |
| domain is set. Instead the currently selected default domain is |
| returned. |
| |
| <p>If the <var>domainname</var> parameter is the empty string the default domain |
| is reset to its initial value, the domain with the name <code>messages</code>. |
| This possibility is questionable to use since the domain <code>messages</code> |
| really never should be used. |
| </p></blockquote></div> |
| |
| <!-- libintl.h --> |
| <!-- GNU --> |
| <div class="defun"> |
| — Function: char * <b>bindtextdomain</b> (<var>const char *domainname, const char *dirname</var>)<var><a name="index-bindtextdomain-812"></a></var><br> |
| <blockquote><p>The <code>bindtextdomain</code> function can be used to specify the directory |
| which contains the message catalogs for domain <var>domainname</var> for the |
| different languages. To be correct, this is the directory where the |
| hierarchy of directories is expected. Details are explained below. |
| |
| <p>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, <samp><span class="file">/foo/bar</span></samp>. Then the program should make a |
| <code>bindtextdomain</code> 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. |
| |
| <p>The <code>bindtextdomain</code> function can be used several times and if the |
| <var>domainname</var> argument is different the previously bound domains |
| will not be overwritten. |
| |
| <p>If the program which wish to use <code>bindtextdomain</code> at some point of |
| time use the <code>chdir</code> function to change the current working |
| directory it is important that the <var>dirname</var> strings ought to be an |
| absolute pathname. Otherwise the addressed directory might vary with |
| the time. |
| |
| <p>If the <var>dirname</var> parameter is the null pointer <code>bindtextdomain</code> |
| returns the currently selected directory for the domain with the name |
| <var>domainname</var>. |
| |
| <p>The <code>bindtextdomain</code> 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 |
| <code>bindtextdomain</code> the return value is <code>NULL</code> and the global |
| variable <var>errno</var> is set accordingly. |
| </p></blockquote></div> |
| |
| </body></html> |
| |
