Commit | Line | Data |
---|---|---|
fd936c91 MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @page | |
8 | @node Internationalization | |
9 | @section Support for Internationalization | |
10 | ||
09ecf78c KR |
11 | Guile provides an interface to GNU @code{gettext} for translating |
12 | message strings (@pxref{Introduction,,, gettext, GNU @code{gettext} | |
13 | utilities}). | |
14 | ||
15 | Messages are collected in domains, so different libraries and programs | |
16 | maintain different message catalogues. The @var{domain} parameter in | |
17 | the functions below is a string (it becomes part of the message | |
18 | catalog filename). | |
19 | ||
20 | When @code{gettext} is not available, or if Guile was configured | |
21 | @samp{--without-nls}, dummy functions doing no translation are | |
22 | provided. | |
23 | ||
24 | @deffn {Scheme Procedure} gettext msg [domain [category]] | |
25 | @deffnx {C Function} scm_gettext (msg, domain, category) | |
26 | Return the translation of @var{msg} in @var{domain}. @var{domain} is | |
27 | optional and defaults to the domain set through @code{textdomain} | |
28 | below. @var{category} is optional and defaults to @code{LC_MESSAGES} | |
29 | (@pxref{Locales}). | |
30 | ||
31 | Normal usage is for @var{msg} to be a literal string. | |
32 | @command{xgettext} can extract those from the source to form a message | |
33 | catalogue ready for translators (@pxref{xgettext Invocation,, Invoking | |
34 | the @command{xgettext} Program, gettext, GNU @code{gettext} | |
35 | utilities}). | |
36 | ||
37 | @example | |
38 | (display (gettext "You are in a maze of twisty passages.")) | |
39 | @end example | |
40 | ||
41 | @code{_} is a commonly used shorthand, an application can make that an | |
42 | alias for @code{gettext}. Or a library can make a definition that | |
43 | uses its specific @var{domain} (so an application can change the | |
44 | default without affecting the library). | |
45 | ||
46 | @example | |
47 | (define (_ msg) (gettext msg "mylibrary")) | |
48 | (display (_ "File not found.")) | |
49 | @end example | |
50 | ||
51 | @code{_} is also a good place to perhaps strip disambiguating extra | |
52 | text from the message string, as for instance in @ref{GUI program | |
53 | problems,, How to use @code{gettext} in GUI programs, gettext, GNU | |
54 | @code{gettext} utilities}. | |
fd936c91 MV |
55 | @end deffn |
56 | ||
09ecf78c KR |
57 | @deffn {Scheme Procedure} ngettext msg msgplural n [domain [category]] |
58 | @deffnx {C Function} scm_ngettext (msg, msgplural, n, domain, category) | |
59 | Return the translation of @var{msg}/@var{msgplural} in @var{domain}, | |
60 | with a plural form chosen appropriately for the number @var{n}. | |
61 | @var{domain} is optional and defaults to the domain set through | |
62 | @code{textdomain} below. @var{category} is optional and defaults to | |
63 | @code{LC_MESSAGES} (@pxref{Locales}). | |
64 | ||
65 | @var{msg} is the singular form, and @var{msgplural} the plural. When | |
66 | no translation is available, @var{msg} is used if @math{@var{n} = 1}, | |
67 | or @var{msgplural} otherwise. When translated, the message catalogue | |
68 | can have a different rule, and can have more than two possible forms. | |
69 | ||
70 | As per @code{gettext} above, normal usage is for @var{msg} and | |
71 | @var{msgplural} to be literal strings, since @command{xgettext} can | |
72 | extract them from the source to build a message catalogue. For | |
73 | example, | |
74 | ||
75 | @example | |
76 | (define (done n) | |
77 | (format #t (ngettext "~a file processed\n" | |
78 | "~a files processed\n" n) | |
79 | n)) | |
80 | ||
81 | (done 1) @print{} 1 file processed | |
82 | (done 3) @print{} 3 files processed | |
83 | @end example | |
84 | ||
85 | It's important to use @code{ngettext} rather than plain @code{gettext} | |
86 | for plurals, since the rules for singular and plural forms in English | |
87 | are not the same in other languages. Only @code{ngettext} will allow | |
40296bab KR |
88 | translators to give correct forms (@pxref{Plural forms,, Additional |
89 | functions for plural forms, gettext, GNU @code{gettext} utilities}). | |
fd936c91 MV |
90 | @end deffn |
91 | ||
09ecf78c KR |
92 | @deffn {Scheme Procedure} textdomain [domain] |
93 | @deffnx {C Function} scm_textdomain (domain) | |
94 | Get or set the default gettext domain. When called with no parameter | |
95 | the current domain is returned. When called with a parameter, | |
96 | @var{domain} is set as the current domain, and that new value | |
97 | returned. For example, | |
98 | ||
99 | @example | |
100 | (textdomain "myprog") | |
101 | @result{} "myprog" | |
102 | @end example | |
fd936c91 MV |
103 | @end deffn |
104 | ||
09ecf78c KR |
105 | @deffn {Scheme Procedure} bindtextdomain domain [directory] |
106 | @deffnx {C Function} scm_bindtextdomain (domain, directory) | |
107 | Get or set the directory under which to find message files for | |
108 | @var{domain}. When called without a @var{directory} the current | |
109 | setting is returned. When called with a @var{directory}, | |
110 | @var{directory} is set for @var{domain} and that new setting returned. | |
111 | For example, | |
112 | ||
113 | @example | |
114 | (bindtextdomain "myprog" "/my/tree/share/locale") | |
115 | @result{} "/my/tree/share/locale" | |
116 | @end example | |
117 | ||
118 | When using Autoconf/Automake, an application should arrange for the | |
119 | configured @code{localedir} to get into the program (by substituting, | |
120 | or by generating a config file) and set that for its domain. This | |
121 | ensures the catalogue can be found even when installed in a | |
122 | non-standard location. | |
fd936c91 MV |
123 | @end deffn |
124 | ||
09ecf78c KR |
125 | @deffn {Scheme Procedure} bind-textdomain-codeset domain [encoding] |
126 | @deffnx {C Function} scm_bind_textdomain_codeset (domain, encoding) | |
127 | Get or set the text encoding to be used by @code{gettext} for messages | |
128 | from @var{domain}. @var{encoding} is a string, the name of a coding | |
129 | system, for instance @nicode{"8859_1"}. (On a Unix/POSIX system the | |
130 | @command{iconv} program can list all available encodings.) | |
131 | ||
132 | When called without an @var{encoding} the current setting is returned, | |
133 | or @code{#f} if none yet set. When called with an @var{encoding}, it | |
134 | is set for @var{domain} and that new setting returned. For example, | |
135 | ||
136 | @example | |
137 | (bind-textdomain-codeset "myprog") | |
138 | @result{} #f | |
139 | (bind-textdomain-codeset "myprog" "latin-9") | |
140 | @result{} "latin-9" | |
141 | @end example | |
142 | ||
143 | The encoding requested can be different from the translated data file, | |
144 | messages will be recoded as necessary. But note that when there is no | |
145 | translation, @code{gettext} returns its @var{msg} unchanged, ie.@: | |
146 | without any recoding. For that reason source message strings are best | |
147 | as plain ASCII. | |
148 | ||
149 | Currently Guile has no understanding of multi-byte characters, and | |
150 | string functions won't recognise character boundaries in multi-byte | |
151 | strings. An application will at least be able to pass such strings | |
152 | through to some output though. Perhaps this will change in the | |
153 | future. | |
fd936c91 MV |
154 | @end deffn |
155 | ||
156 | @c Local Variables: | |
157 | @c TeX-master: "guile.texi" | |
158 | @c End: |