Lines Matching refs:code
10 ways. One could add all the different languages in the source code and
13 cumbersome (the code must be changed) and the code itself can become
22 officially defined by the POSIX standard. The @code{catgets} family of
46 * Message catalogs a la X/Open:: The @code{catgets} family of functions.
47 * The Uniforum approach:: The @code{gettext} family of functions.
54 The @code{catgets} functions are based on the simple scheme:
57 Associate every message to translate in the source code with a unique
63 sure the meaning of the identifier in the program code and in the
71 All the types, constants and functions for the @code{catgets} functions
75 * The catgets Functions:: The @code{catgets} function family.
79 * Common Usage:: How to use the @code{catgets} interface.
84 @subsection The @code{catgets} function family
113 The @code{catopen} function tries to locate the message data file named
118 The return value is @code{(nl_catd) -1} in case the function failed and
119 no catalog was loaded. The global variable @code{errno} contains a code
135 To tell the @code{catopen} function where the catalog for the program
136 can be found the user can set the environment variable @code{NLSPATH} to
139 Instead it is a format string (similar to @code{printf}'s). An example
148 observe are the format string, @code{%L} and @code{%N} in this case.
149 The @code{catopen} function knows about several of them and the
152 @table @code
156 @code{catgets}.
167 @code{@var{lang}[_@var{terr}[.@var{codeset}]]} and this format uses the
181 Since @code{%} is used as a meta character there must be a way to
182 express the @code{%} character in the result itself. Using @code{%%}
183 does this just like it works for @code{printf}.
187 Using @code{NLSPATH} allows arbitrary directories to be searched for
189 If the @code{NLSPATH} environment variable is not set, the default value
197 where @var{prefix} is given to @code{configure} while installing @theglibc{}
198 (this value is in many cases @code{/usr} or the empty string).
204 @code{NLSPATH} environment variable is not used. The catalog must exist
208 to all other platforms providing the @code{catgets} interface.
216 @code{catopen}. If the value is @code{NL_CAT_LOCALE} (which is defined
217 in @file{nl_types.h}) then the @code{catopen} function uses the name of
218 the locale currently selected for the @code{LC_MESSAGES} category.
220 If @var{flag} is zero the @code{LANG} environment variable is examined.
225 form @code{@var{lang}[_@var{terr}[.@var{codeset}]]} as explained above.
226 If no environment variable is set the @code{"C"} locale is used which
231 @var{string} parameter. So a piece of code to decide whether a
245 When an error occurs the global variable @code{errno} is set to
263 to the @code{setlocale} function. It is not necessary that the locale
264 data files for this locale exist and calling @code{setlocale} succeeds.
265 The @code{catopen} function directly reads the values of the environment
271 The function @code{catgets} has to be used to access the message catalog
272 previously opened using the @code{catopen} function. The
274 @code{catopen}.
300 It is somewhat uncomfortable to write a program using the @code{catgets}
303 of the messages at the same time the code is written. And the work
314 The @code{catclose} function can be used to free the resources
316 to @code{catopen}. If the resources can be successfully freed the
317 function returns @code{0}. Otherwise it returns @code{@minus{}1} and the
318 global variable @code{errno} is set. Errors can occur if the catalog
319 descriptor @var{catalog_desc} is not valid in which case @code{errno} is
320 set to @code{EBADF}.
329 @code{catopen} function is to write all the message text to the
340 Lines which contain as the first non-whitespace character a @code{$}
345 @code{$set} followed by a whitespace character an additional argument
366 @code{$delset} followed by a whitespace character an additional argument
382 with a @code{$set} command again messages could be added and these
387 @code{$quote}, the quoting character used for this input file is
389 @code{$quote}. If no non-whitespace character is present before the
394 @code{$quote} sequence present newline need not be escaped. Instead a
399 @code{"}. Then any appearance of the @code{"} in the strings must
400 be escaped using the backslash (i.e., @code{\"} must be written).
418 one limitation with the identifier: it must not be @code{Set}. The
423 (@code{\n}, @code{\t}, @code{\v}, @code{\b}, @code{\r}, @code{\f},
424 @code{\\}, and @code{\@var{nnn}}, where @var{nnn} is the octal coding of
425 a character code).
449 Lines 1 and 9 are comments since they start with @code{$} followed by
452 The quoting character is set to @code{"}. Otherwise the quotes in the
454 message with the identifier @code{two} would lose its leading whitespace.
462 use in a running program. The @code{catopen} function would have to
464 easy and the whole process is pretty slow. Therefore the @code{catgets}
466 format. There is a special program @code{gencat} which is explained in
475 these files are always created by the @code{gencat} program. The
477 @code{gencat} program and so the interested reader can look through
485 The @code{gencat} program is specified in the X/Open standard and the
489 @code{catgets} functions.
491 The @code{gencat} program can be invoked in two ways:
517 The @code{gencat} program works by concatenating all input files and
527 The following table shows the options understood by the @code{gencat}
547 number of C preprocessor @code{#define}s to associate a name with a
558 @subsection How to use the @code{catgets} interface
560 The @code{catgets} functions can be used in two different ways. By
577 @var{catgets} is retrieved from a call to @code{catopen} which is
578 normally done once at the program start. The @code{"string"} is the
594 cannot be discovered by the compiler or the @code{catgets} functions.
597 recognized as wrong. Think about the translations for @code{"true"} and
598 @code{"false"} being exchanged. This could result in a disaster.
624 call the @code{gencat} program as follows (assume @file{ex.msg} contains
645 but this is not necessary. The @code{gencat} program can take care for
652 string @code{Set}. So @code{SetOnetwo} means this macro can be used to
653 access the translation with identifier @code{two} in the message set
654 @code{SetOne}.
657 string @code{Set} is used in the place of the message identifier.
659 If in the code the second string of the set @code{SetOne} is used the C
660 code should look like this:
669 code. (The text of the string is normally not the same; this is only
677 famous greeting program. We start by writing the code as usual:
713 What remains unspecified here are the constants @code{SetMainSet} and
714 @code{SetMainHello}. These are the symbolic names describing the
717 process it using the @code{gencat} program.
744 The call of the @code{gencat} program creates the missing header file
747 directory in which the @code{catopen} function will try to locate it.
748 Please check the @code{LC_ALL} environment variable and the default path
749 for @code{catopen} presented in the description above.
762 The code of the @file{libintl} from GNU @file{gettext} is the same as
763 the code in @theglibc{}. So the documentation in the GNU
771 Though the @code{catgets} functions are available by default on more
772 systems the @code{gettext} interface is at least as portable as the
778 * Message catalogs with gettext:: The @code{gettext} family of functions.
780 for @code{gettext}.
785 @subsection The @code{gettext} family of functions
787 The paradigms underlying the @code{gettext} approach to message
788 translations is different from that of the @code{catgets} functions the
798 @code{gettext} uses.
799 * GUI program problems:: How to use @code{gettext} in GUI programs.
801 the way @code{gettext} works.
807 The @code{gettext} functions have a very simple interface. The most
810 different from the @code{catgets} approach where an extra key is
817 string. The task of the @code{gettext} function is to compare the
821 like in @code{catgets}.
823 The @code{gettext} approach has some advantages but also some
827 All the definitions and declarations for @code{gettext} can be found in
836 The @code{gettext} function searches the currently selected message
841 Please note that although the return value is @code{char *} the
851 The @code{gettext} function does not modify the value of the global
852 @code{errno} variable. This is necessary to make it possible to write
859 Here the @code{errno} value is used in the @code{printf} function while
860 processing the @code{%m} format element and if the @code{gettext}
861 function would change this value (it is called before @code{printf} is
876 uses the @code{gettext} functions but since it must not depend on a
884 The @code{dgettext} function acts just like the @code{gettext}
888 pointer the @code{dgettext} function is exactly equivalent to
889 @code{gettext} since the default value for the domain name is used.
891 As for @code{gettext} the return value type is @code{char *} which is an
993 The @code{dcgettext} adds another argument to those which
994 @code{dgettext} takes. This argument @var{category} specifies the last
999 The @code{dgettext} function can be expressed in terms of
1000 @code{dcgettext} by using
1015 @file{locale.h}. Normally the available values are @code{LC_CTYPE},
1016 @code{LC_COLLATE}, @code{LC_MESSAGES}, @code{LC_MONETARY},
1017 @code{LC_NUMERIC}, and @code{LC_TIME}. Please note that @code{LC_ALL}
1021 The @code{dcgettext} function is only implemented for compatibility with
1022 other systems which have @code{gettext} functions. There is not really
1024 than @code{LC_MESSAGES} for the @var{category} parameter. We are
1027 As for @code{gettext} the return value type is @code{char *} which is an
1036 @code{gettext}, @code{dgettext} and @code{dcgettext} functions.
1047 underlying mechanism which controls all this. The code is complicated
1051 performed by the @code{catgets} functions:
1070 @code{gettext} and this is also what the @code{catgets} functions are
1078 German translation one could write @code{de}, @code{german}, or
1079 @code{deutsch} and the program should always react the same.
1083 specifies @code{de_DE.ISO-8859-1} which means German, spoken in Germany,
1086 there could be a catalog matching @code{de} and if the character set
1109 named @code{libc} while the program using the C Library could use a
1110 domain named @code{foo}. The important point is that at any time
1123 The @code{textdomain} function sets the default domain, which is used in
1124 all future @code{gettext} calls, to @var{domainname}. Please note that
1125 @code{dgettext} and @code{dcgettext} calls are not influenced if the
1128 Before the first call to @code{textdomain} the default domain is
1129 @code{messages}. This is the name specified in the specification of
1130 the @code{gettext} API. This name is as good as any other name. No
1136 @code{NULL} and the global variable @code{errno} is set to @code{ENOMEM}.
1137 Despite the return value type being @code{char *} the return string must
1138 not be changed. It is allocated internally by the @code{textdomain}
1146 is reset to its initial value, the domain with the name @code{messages}.
1147 This possibility is questionable to use since the domain @code{messages}
1161 The @code{bindtextdomain} function can be used to specify the directory
1169 @code{bindtextdomain} call to bind the domain for the current program to
1174 The @code{bindtextdomain} function can be used several times and if the
1178 If the program which wish to use @code{bindtextdomain} at some point of
1179 time use the @code{chdir} function to change the current working
1184 If the @var{dirname} parameter is the null pointer @code{bindtextdomain}
1188 The @code{bindtextdomain} function returns a pointer to a string
1192 @code{bindtextdomain} the return value is @code{NULL} and the global
1193 variable @code{errno} is set accordingly.
1200 The functions of the @code{gettext} family described so far (and all the
1201 @code{catgets} functions as well) have one problem in the real world
1205 Looking through Unix source code before the time anybody thought about
1207 code similar to the following:
1214 After the first complaints from people internationalizing the code people
1216 @code{"file(s)"}. Both look unnatural and should be avoided. First
1251 solve the problem in their code. This would be localization since it is
1253 extended @code{gettext} interface should be used.
1261 @code{gettext} behavior). In this case the rules for Germanic language
1268 (as well as the GNU @code{gettext} package) is written as part of the
1277 The @code{ngettext} function is similar to the @code{gettext} function
1283 message catalog is found @var{msgid1} is returned if @code{n == 1},
1284 otherwise @code{msgid2}.
1293 @code{printf} function as well. It is not sufficient to pass it only to
1294 @code{ngettext}.
1301 The @code{dngettext} is similar to the @code{dgettext} function in the
1304 parameters are handled in the same way @code{ngettext} handles them.
1311 The @code{dcngettext} is similar to the @code{dcgettext} function in the
1314 parameters are handled in the same way @code{ngettext} handles them.
1329 hardcoding the information in the code (which still would require the
1331 details are explained in the GNU @code{gettext} manual. Here only a
1335 header entry (the one with the empty @code{msgid} string). It looks
1342 The @code{nplurals} value must be a decimal number which specifies how
1344 following @code{plural} is an expression using the C language
1346 must be decimal, and the only variable allowed is @code{n}. This
1348 @code{ngettext}, @code{dngettext}, or @code{dcngettext} is called. The
1350 of the variable @code{n} in the expression. The resulting value then
1352 value of @code{nplurals}.
1542 @subsubsection How to specify the output character set @code{gettext} uses
1544 @code{gettext} not only looks up a translation in a message catalog, it
1551 The output character set is, by default, the value of @code{nl_langinfo
1552 (CODESET)}, which depends on the @code{LC_CTYPE} part of the current
1554 (e.g. UTF-8) can request that @code{gettext} and related functions
1556 @code{bind_textdomain_codeset} function.
1558 Note that the @var{msgid} argument to @code{gettext} is not subject to
1559 character set conversion. Also, when @code{gettext} does not find a
1569 The @code{bind_textdomain_codeset} function can be used to specify the
1572 for the @code{iconv_open} function, or a null pointer.
1575 @code{bind_textdomain_codeset} returns the currently selected codeset
1576 for the domain with the name @var{domainname}. It returns @code{NULL} if
1579 The @code{bind_textdomain_codeset} function can be used several times.
1583 The @code{bind_textdomain_codeset} function returns a pointer to a
1587 @code{bind_textdomain_codeset}, the return value is @code{NULL} and the
1588 global variable @code{errno} is set accordingly.
1593 @subsubsection How to use @code{gettext} in GUI programs
1595 One place where the @code{gettext} functions, if used normally, have big
1605 As a consequence many people say that the @code{gettext} approach is
1606 wrong and instead @code{catgets} should be used which indeed does not
1608 handle these kind of problems with the @code{gettext} functions.
1624 To have the strings @code{File}, @code{Printer}, @code{Open},
1625 @code{New}, @code{Select}, and @code{Connect} translated there has to be
1626 at some point in the code a call to a function of the @code{gettext}
1628 @code{Open}. The translations might not be the same and therefore we
1649 Now all the strings are different and if now instead of @code{gettext}
1669 for the Menu entries and therefore contains a @code{|} character. We
1674 the @code{gettext} calls with calls to @code{sgettext} (this is normally
1679 @code{sgettext} functions as an inline function or as a macro like this:
1691 The other @code{gettext} functions (@code{dgettext}, @code{dcgettext}
1692 and the @code{ngettext} equivalents) can and should have corresponding
1709 examples above used @code{|} which is a quite good choice because it
1715 compiles (e.g., @code{|} is not required to exist for @w{ISO C}; this is
1727 @subsubsection User influence on @code{gettext}
1734 The POSIX locale model uses the environment variables @code{LC_COLLATE},
1735 @code{LC_CTYPE}, @code{LC_MESSAGES}, @code{LC_MONETARY}, @code{LC_NUMERIC},
1736 and @code{LC_TIME} to select the locale which is to be used. This way
1738 @code{gettext} functions also take advantage of this.
1759 files. If the program executed the @code{bindtextdomain} function for
1760 the message domain that is currently handled, the @code{dir_name}
1762 the second parameter. I.e., @code{bindtextdomain} allows overwriting
1767 in the program code. For @code{gettext} and @code{dgettext} this is
1768 always @code{LC_MESSAGES}, for @code{dcgettext} this is selected by the
1770 ever use a category other than @code{LC_MESSAGES}.
1773 like for the @code{setlocale} function here comes the user selection
1776 the lookup process. In detail, for the category @code{LC_xxx} the
1779 @table @code
1786 This looks very familiar. With the exception of the @code{LANGUAGE}
1788 @code{setlocale} function uses. But why introduce the @code{LANGUAGE}
1792 different to what is expected by the @code{setlocale} function. If we
1793 would set @code{LC_ALL} to a value following the extended syntax that
1794 would mean the @code{setlocale} function will never be able to use the
1799 While for the @code{LC_xxx} variables the value should consist of
1800 exactly one specification of a locale the @code{LANGUAGE} variable's
1808 the @code{textdomain} function or which was given to @code{dgettext} or
1809 @code{dcgettext} as the first parameter. Now it becomes obvious that a
1810 good choice for the domain name in the program code is a string which is
1812 the domain name is @code{libc}.
1815 A limited piece of example code should show how the program is supposed
1827 At the program start the default domain is @code{messages}, and the
1828 default locale is "C". The @code{setlocale} call sets the locale
1830 functioning of @code{gettext} relies on the correct setting of the
1831 @code{LC_MESSAGES} locale (for looking up the message catalog) and
1832 of the @code{LC_CTYPE} locale (for the character set conversion).
1833 The @code{textdomain} call changes the default domain to
1834 @code{test-package}. The @code{bindtextdomain} call specifies that
1835 the message catalogs for the domain @code{test-package} can be found
1838 If the user sets in her/his environment the variable @code{LANGUAGE}
1839 to @code{de} the @code{gettext} function will try to use the
1849 In the above example we assumed the @code{LANGUAGE} environment
1850 variable to be @code{de}. This might be an appropriate selection but what
1851 happens if the user wants to use @code{LC_ALL} because of the wider
1852 usability and here the required value is @code{de_DE.ISO-8859-1}? We
1857 The @code{gettext} functions know about situations like this and can
1866 @code{language[_territory[.codeset]][@@modifier]}
1873 @code{codeset}
1875 @code{normalized codeset}
1877 @code{territory}
1879 @code{modifier}
1882 The @code{language} field will never be dropped for obvious reasons.
1884 The only new thing is the @code{normalized codeset} entry. This is
1888 @w{88591}, @w{iso8859-1}, or @w{iso_8859-1}. The @code{normalized
1898 If the same only contains digits prepend the string @code{"iso"}.
1902 So all of the above names will be normalized to @code{iso88591}. This
1907 locale (e.g., @code{de} and @code{german}). To be of help in this
1908 situation the locale implementation and also the @code{gettext}
1930 @subsection Programs to handle message catalogs for @code{gettext}
1932 @Theglibc{} does not contain the source code for the programs to
1933 handle message catalogs for the @code{gettext} functions. As part of
1936 package by far exceeds the abilities of the @code{gencat} program
1937 described above for the @code{catgets} functions.
1939 There is a program @code{msgfmt} which is the equivalent program to the
1940 @code{gencat} program. It generates from the human-readable and
1942 the @code{gettext} functions. But there are several more programs
1945 The @code{xgettext} program can be used to automatically extract the
1949 @code{gettext} et.al and the rest will be done by @code{xgettext}. This
1957 catalogs. Besides marking the translatable strings in the source code and