Commit | Line | Data |
---|---|---|
fd936c91 MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
4d0fd346 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2009, 2010 |
fd936c91 MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
fd936c91 MV |
7 | @node Internationalization |
8 | @section Support for Internationalization | |
9 | ||
b89c4943 LC |
10 | @cindex internationalization |
11 | @cindex i18n | |
12 | ||
a2f00b9b LC |
13 | Guile provides internationalization@footnote{For concision and style, |
14 | programmers often like to refer to internationalization as ``i18n''.} | |
15 | support for Scheme programs in two ways. First, procedures to | |
16 | manipulate text and data in a way that conforms to particular cultural | |
17 | conventions (i.e., in a ``locale-dependent'' way) are provided in the | |
18 | @code{(ice-9 i18n)}. Second, Guile allows the use of GNU | |
19 | @code{gettext} to translate program message strings. | |
b89c4943 LC |
20 | |
21 | @menu | |
a2f00b9b LC |
22 | * i18n Introduction:: Introduction to Guile's i18n support. |
23 | * Text Collation:: Sorting strings and characters. | |
24 | * Character Case Mapping:: Case mapping. | |
25 | * Number Input and Output:: Parsing and printing numbers. | |
26 | * Accessing Locale Information:: Detailed locale information. | |
27 | * Gettext Support:: Translating message strings. | |
b89c4943 LC |
28 | @end menu |
29 | ||
30 | ||
a2f00b9b LC |
31 | @node i18n Introduction, Text Collation, Internationalization, Internationalization |
32 | @subsection Internationalization with Guile | |
b89c4943 | 33 | |
a2f00b9b LC |
34 | In order to make use of the functions described thereafter, the |
35 | @code{(ice-9 i18n)} module must be imported in the usual way: | |
b89c4943 LC |
36 | |
37 | @example | |
38 | (use-modules (ice-9 i18n)) | |
39 | @end example | |
40 | ||
b89c4943 LC |
41 | @cindex cultural conventions |
42 | ||
43 | The @code{(ice-9 i18n)} module provides procedures to manipulate text | |
44 | and other data in a way that conforms to the cultural conventions | |
45 | chosen by the user. Each region of the world or language has its own | |
46 | customs to, for instance, represent real numbers, classify characters, | |
47 | collate text, etc. All these aspects comprise the so-called | |
48 | ``cultural conventions'' of that region or language. | |
49 | ||
50 | @cindex locale | |
51 | @cindex locale category | |
52 | ||
53 | Computer systems typically refer to a set of cultural conventions as a | |
54 | @dfn{locale}. For each particular aspect that comprise those cultural | |
55 | conventions, a @dfn{locale category} is defined. For instance, the | |
56 | way characters are classified is defined by the @code{LC_CTYPE} | |
57 | category, while the language in which program messages are issued to | |
58 | the user is defined by the @code{LC_MESSAGES} category | |
59 | (@pxref{Locales, General Locale Information} for details). | |
60 | ||
61 | @cindex locale object | |
62 | ||
63 | The procedures provided by this module allow the development of | |
64 | programs that adapt automatically to any locale setting. As we will | |
a2f00b9b LC |
65 | see later, many of these procedures can optionally take a @dfn{locale |
66 | object} argument. This additional argument defines the locale | |
67 | settings that must be followed by the invoked procedure. When it is | |
68 | omitted, then the current locale settings of the process are followed | |
69 | (@pxref{Locales, @code{setlocale}}). | |
b89c4943 LC |
70 | |
71 | The following procedures allow the manipulation of such locale | |
72 | objects. | |
73 | ||
a2f00b9b LC |
74 | @deffn {Scheme Procedure} make-locale category-list locale-name [base-locale] |
75 | @deffnx {C Function} scm_make_locale (category_list, locale_name, base_locale) | |
b89c4943 LC |
76 | Return a reference to a data structure representing a set of locale |
77 | datasets. @var{locale-name} should be a string denoting a particular | |
a2f00b9b LC |
78 | locale (e.g., @code{"aa_DJ"}) and @var{category-list} should be either |
79 | a list of locale categories or a single category as used with | |
80 | @code{setlocale} (@pxref{Locales, @code{setlocale}}). Optionally, if | |
81 | @code{base-locale} is passed, it should be a locale object denoting | |
82 | settings for categories not listed in @var{category-list}. | |
83 | ||
84 | The following invocation creates a locale object that combines the use | |
85 | of Swedish for messages and character classification with the | |
86 | default settings for the other categories (i.e., the settings of the | |
87 | default @code{C} locale which usually represents conventions in use in | |
88 | the USA): | |
b89c4943 LC |
89 | |
90 | @example | |
a2f00b9b | 91 | (make-locale (list LC_MESSAGE LC_CTYPE) "sv_SE") |
b89c4943 LC |
92 | @end example |
93 | ||
a2f00b9b LC |
94 | The following example combines the use of Esperanto messages and |
95 | conventions with monetary conventions from Croatia: | |
b89c4943 LC |
96 | |
97 | @example | |
a2f00b9b LC |
98 | (make-locale LC_MONETARY "hr_HR" |
99 | (make-locale LC_ALL "eo_EO")) | |
b89c4943 LC |
100 | @end example |
101 | ||
102 | A @code{system-error} exception (@pxref{Handling Errors}) is raised by | |
103 | @code{make-locale} when @var{locale-name} does not match any of the | |
104 | locales compiled on the system. Note that on non-GNU systems, this | |
105 | error may be raised later, when the locale object is actually used. | |
106 | ||
107 | @end deffn | |
108 | ||
109 | @deffn {Scheme Procedure} locale? obj | |
110 | @deffnx {C Function} scm_locale_p (obj) | |
111 | Return true if @var{obj} is a locale object. | |
112 | @end deffn | |
113 | ||
a2f00b9b LC |
114 | @defvr {Scheme Variable} %global-locale |
115 | @defvrx {C Variable} scm_global_locale | |
116 | This variable is bound to a locale object denoting the current process | |
117 | locale as installed using @code{setlocale ()} (@pxref{Locales}). It | |
118 | may be used like any other locale object, including as a third | |
119 | argument to @code{make-locale}, for instance. | |
120 | @end defvr | |
121 | ||
122 | ||
123 | @node Text Collation, Character Case Mapping, i18n Introduction, Internationalization | |
124 | @subsection Text Collation | |
125 | ||
126 | The following procedures provide support for text collation, i.e., | |
127 | locale-dependent string and character sorting. | |
b89c4943 LC |
128 | |
129 | @deffn {Scheme Procedure} string-locale<? s1 s2 [locale] | |
130 | @deffnx {C Function} scm_string_locale_lt (s1, s2, locale) | |
a2f00b9b | 131 | @deffnx {Scheme Procedure} string-locale>? s1 s2 [locale] |
b89c4943 | 132 | @deffnx {C Function} scm_string_locale_gt (s1, s2, locale) |
a2f00b9b LC |
133 | @deffnx {Scheme Procedure} string-locale-ci<? s1 s2 [locale] |
134 | @deffnx {C Function} scm_string_locale_ci_lt (s1, s2, locale) | |
135 | @deffnx {Scheme Procedure} string-locale-ci>? s1 s2 [locale] | |
136 | @deffnx {C Function} scm_string_locale_ci_gt (s1, s2, locale) | |
b89c4943 LC |
137 | Compare strings @var{s1} and @var{s2} in a locale-dependent way. If |
138 | @var{locale} is provided, it should be locale object (as returned by | |
139 | @code{make-locale}) and will be used to perform the comparison; | |
a2f00b9b LC |
140 | otherwise, the current system locale is used. For the @code{-ci} |
141 | variants, the comparison is made in a case-insensitive way. | |
b89c4943 LC |
142 | @end deffn |
143 | ||
144 | @deffn {Scheme Procedure} string-locale-ci=? s1 s2 [locale] | |
145 | @deffnx {C Function} scm_string_locale_ci_eq (s1, s2, locale) | |
146 | Compare strings @var{s1} and @var{s2} in a case-insensitive, and | |
147 | locale-dependent way. If @var{locale} is provided, it should be | |
a2f00b9b | 148 | a locale object (as returned by @code{make-locale}) and will be used to |
b89c4943 LC |
149 | perform the comparison; otherwise, the current system locale is used. |
150 | @end deffn | |
151 | ||
152 | @deffn {Scheme Procedure} char-locale<? c1 c2 [locale] | |
153 | @deffnx {C Function} scm_char_locale_lt (c1, c2, locale) | |
a2f00b9b | 154 | @deffnx {Scheme Procedure} char-locale>? c1 c2 [locale] |
b89c4943 | 155 | @deffnx {C Function} scm_char_locale_gt (c1, c2, locale) |
a2f00b9b | 156 | @deffnx {Scheme Procedure} char-locale-ci<? c1 c2 [locale] |
b89c4943 | 157 | @deffnx {C Function} scm_char_locale_ci_lt (c1, c2, locale) |
a2f00b9b | 158 | @deffnx {Scheme Procedure} char-locale-ci>? c1 c2 [locale] |
b89c4943 | 159 | @deffnx {C Function} scm_char_locale_ci_gt (c1, c2, locale) |
a2f00b9b LC |
160 | Compare characters @var{c1} and @var{c2} according to either |
161 | @var{locale} (a locale object as returned by @code{make-locale}) or | |
162 | the current locale. For the @code{-ci} variants, the comparison is | |
163 | made in a case-insensitive way. | |
b89c4943 LC |
164 | @end deffn |
165 | ||
166 | @deffn {Scheme Procedure} char-locale-ci=? c1 c2 [locale] | |
167 | @deffnx {C Function} scm_char_locale_ci_eq (c1, c2, locale) | |
168 | Return true if character @var{c1} is equal to @var{c2}, in a case | |
169 | insensitive way according to @var{locale} or to the current locale. | |
170 | @end deffn | |
171 | ||
a2f00b9b LC |
172 | @node Character Case Mapping, Number Input and Output, Text Collation, Internationalization |
173 | @subsection Character Case Mapping | |
174 | ||
b89c4943 LC |
175 | The procedures below provide support for ``character case mapping'', |
176 | i.e., to convert characters or strings to their upper-case or | |
177 | lower-case equivalent. Note that SRFI-13 provides procedures that | |
178 | look similar (@pxref{Alphabetic Case Mapping}). However, the SRFI-13 | |
179 | procedures are locale-independent. Therefore, they do not take into | |
180 | account specificities of the customs in use in a particular language | |
181 | or region of the world. For instance, while most languages using the | |
182 | Latin alphabet map lower-case letter ``i'' to upper-case letter ``I'', | |
183 | Turkish maps lower-case ``i'' to ``Latin capital letter I with dot | |
a2f00b9b LC |
184 | above''. The following procedures allow programmers to provide |
185 | idiomatic character mapping. | |
b89c4943 LC |
186 | |
187 | @deffn {Scheme Procedure} char-locale-downcase chr [locale] | |
188 | @deffnx {C Function} scm_char_locale_upcase (chr, locale) | |
189 | Return the lowercase character that corresponds to @var{chr} according | |
190 | to either @var{locale} or the current locale. | |
191 | @end deffn | |
192 | ||
193 | @deffn {Scheme Procedure} char-locale-upcase chr [locale] | |
194 | @deffnx {C Function} scm_char_locale_downcase (chr, locale) | |
195 | Return the uppercase character that corresponds to @var{chr} according | |
196 | to either @var{locale} or the current locale. | |
197 | @end deffn | |
198 | ||
820f33aa JG |
199 | @deffn {Scheme Procedure} char-locale-titlecase chr [locale] |
200 | @deffnx {C Function} scm_char_locale_titlecase (chr, locale) | |
201 | Return the titlecase character that corresponds to @var{chr} according | |
202 | to either @var{locale} or the current locale. | |
203 | @end deffn | |
204 | ||
b89c4943 LC |
205 | @deffn {Scheme Procedure} string-locale-upcase str [locale] |
206 | @deffnx {C Function} scm_string_locale_upcase (str, locale) | |
207 | Return a new string that is the uppercase version of @var{str} | |
208 | according to either @var{locale} or the current locale. | |
209 | @end deffn | |
210 | ||
211 | @deffn {Scheme Procedure} string-locale-downcase str [locale] | |
212 | @deffnx {C Function} scm_string_locale_downcase (str, locale) | |
213 | Return a new string that is the down-case version of @var{str} | |
214 | according to either @var{locale} or the current locale. | |
215 | @end deffn | |
216 | ||
820f33aa JG |
217 | @deffn {Scheme Procedure} string-locale-titlecase str [locale] |
218 | @deffnx {C Function} scm_string_locale_titlecase (str, locale) | |
219 | Return a new string that is the titlecase version of @var{str} | |
220 | according to either @var{locale} or the current locale. | |
221 | @end deffn | |
222 | ||
a2f00b9b LC |
223 | @node Number Input and Output, Accessing Locale Information, Character Case Mapping, Internationalization |
224 | @subsection Number Input and Output | |
225 | ||
226 | The following procedures allow programs to read and write numbers | |
b89c4943 LC |
227 | written according to a particular locale. As an example, in English, |
228 | ``ten thousand and a half'' is usually written @code{10,000.5} while | |
a2f00b9b LC |
229 | in French it is written @code{10 000,5}. These procedures allow such |
230 | differences to be taken into account. | |
b89c4943 | 231 | |
a2f00b9b | 232 | @findex strtod |
b89c4943 LC |
233 | @deffn {Scheme Procedure} locale-string->integer str [base [locale]] |
234 | @deffnx {C Function} scm_locale_string_to_integer (str, base, locale) | |
235 | Convert string @var{str} into an integer according to either | |
236 | @var{locale} (a locale object as returned by @code{make-locale}) or | |
237 | the current process locale. If @var{base} is specified, then it | |
238 | determines the base of the integer being read (e.g., @code{16} for an | |
239 | hexadecimal number, @code{10} for a decimal number); by default, | |
a2f00b9b LC |
240 | decimal numbers are read. Return two values (@pxref{Multiple |
241 | Values}): an integer (on success) or @code{#f}, and the number of | |
242 | characters read from @var{str} (@code{0} on failure). | |
243 | ||
244 | This function is based on the C library's @code{strtol} function | |
245 | (@pxref{Parsing of Integers, @code{strtol},, libc, The GNU C Library | |
246 | Reference Manual}). | |
b89c4943 LC |
247 | @end deffn |
248 | ||
a2f00b9b | 249 | @findex strtod |
b89c4943 LC |
250 | @deffn {Scheme Procedure} locale-string->inexact str [locale] |
251 | @deffnx {C Function} scm_locale_string_to_inexact (str, locale) | |
252 | Convert string @var{str} into an inexact number according to either | |
253 | @var{locale} (a locale object as returned by @code{make-locale}) or | |
a2f00b9b LC |
254 | the current process locale. Return two values (@pxref{Multiple |
255 | Values}): an inexact number (on success) or @code{#f}, and the number | |
256 | of characters read from @var{str} (@code{0} on failure). | |
257 | ||
258 | This function is based on the C library's @code{strtod} function | |
259 | (@pxref{Parsing of Floats, @code{strtod},, libc, The GNU C Library | |
260 | Reference Manual}). | |
261 | @end deffn | |
262 | ||
263 | @deffn {Scheme Procedure} number->locale-string number [fraction-digits [locale]] | |
264 | Convert @var{number} (an inexact) into a string according to the | |
265 | cultural conventions of either @var{locale} (a locale object) or the | |
266 | current locale. Optionally, @var{fraction-digits} may be bound to an | |
267 | integer specifying the number of fractional digits to be displayed. | |
268 | @end deffn | |
269 | ||
270 | @deffn {Scheme Procedure} monetary-amount->locale-string amount intl? [locale] | |
271 | Convert @var{amount} (an inexact denoting a monetary amount) into a | |
272 | string according to the cultural conventions of either @var{locale} (a | |
273 | locale object) or the current locale. If @var{intl?} is true, then | |
274 | the international monetary format for the given locale is used | |
275 | (@pxref{Currency Symbol, international and locale monetary formats,, | |
276 | libc, The GNU C Library Reference Manual}). | |
277 | @end deffn | |
278 | ||
279 | ||
280 | @node Accessing Locale Information, Gettext Support, Number Input and Output, Internationalization | |
281 | @subsection Accessing Locale Information | |
282 | ||
283 | @findex nl_langinfo | |
284 | @cindex low-level locale information | |
285 | It is sometimes useful to obtain very specific information about a | |
286 | locale such as the word it uses for days or months, its format for | |
287 | representing floating-point figures, etc. The @code{(ice-9 i18n)} | |
288 | module provides support for this in a way that is similar to the libc | |
289 | functions @code{nl_langinfo ()} and @code{localeconv ()} | |
290 | (@pxref{Locale Information, accessing locale information from C,, | |
291 | libc, The GNU C Library Reference Manual}). The available functions | |
292 | are listed below. | |
293 | ||
294 | @deffn {Scheme Procedure} locale-encoding [locale] | |
295 | Return the name of the encoding (a string whose interpretation is | |
296 | system-dependent) of either @var{locale} or the current locale. | |
297 | @end deffn | |
298 | ||
299 | The following functions deal with dates and times. | |
300 | ||
301 | @deffn {Scheme Procedure} locale-day day [locale] | |
302 | @deffnx {Scheme Procedure} locale-day-short day [locale] | |
303 | @deffnx {Scheme Procedure} locale-month month [locale] | |
304 | @deffnx {Scheme Procedure} locale-month-short month [locale] | |
305 | Return the word (a string) used in either @var{locale} or the current | |
306 | locale to name the day (or month) denoted by @var{day} (or | |
307 | @var{month}), an integer between 1 and 7 (or 1 and 12). The | |
308 | @code{-short} variants provide an abbreviation instead of a full name. | |
309 | @end deffn | |
310 | ||
311 | @deffn {Scheme Procedure} locale-am-string [locale] | |
312 | @deffnx {Scheme Procedure} locale-pm-string [locale] | |
313 | Return a (potentially empty) string that is used to denote @i{ante | |
314 | meridiem} (or @i{post meridiem}) hours in 12-hour format. | |
315 | @end deffn | |
316 | ||
317 | @deffn {Scheme Procedure} locale-date+time-format [locale] | |
318 | @deffnx {Scheme Procedure} locale-date-format [locale] | |
319 | @deffnx {Scheme Procedure} locale-time-format [locale] | |
320 | @deffnx {Scheme Procedure} locale-time+am/pm-format [locale] | |
321 | @deffnx {Scheme Procedure} locale-era-date-format [locale] | |
322 | @deffnx {Scheme Procedure} locale-era-date+time-format [locale] | |
323 | @deffnx {Scheme Procedure} locale-era-time-format [locale] | |
324 | These procedures return format strings suitable to @code{strftime} | |
325 | (@pxref{Time}) that may be used to display (part of) a date/time | |
326 | according to certain constraints and to the conventions of either | |
327 | @var{locale} or the current locale (@pxref{The Elegant and Fast Way, | |
328 | the @code{nl_langinfo ()} items,, libc, The GNU C Library Reference | |
329 | Manual}). | |
330 | @end deffn | |
331 | ||
332 | @deffn {Scheme Procedure} locale-era [locale] | |
333 | @deffnx {Scheme Procedure} locale-era-year [locale] | |
334 | These functions return, respectively, the era and the year of the | |
335 | relevant era used in @var{locale} or the current locale. Most locales | |
336 | do not define this value. In this case, the empty string is returned. | |
337 | An example of a locale that does define this value is the Japanese | |
338 | one. | |
b89c4943 LC |
339 | @end deffn |
340 | ||
a2f00b9b LC |
341 | The following procedures give information about number representation. |
342 | ||
343 | @deffn {Scheme Procedure} locale-decimal-point [locale] | |
344 | @deffnx {Scheme Procedure} locale-thousands-separator [locale] | |
345 | These functions return a string denoting the representation of the | |
346 | decimal point or that of the thousand separator (respectively) for | |
347 | either @var{locale} or the current locale. | |
348 | @end deffn | |
349 | ||
350 | @deffn {Scheme Procedure} locale-digit-grouping [locale] | |
351 | Return a (potentially circular) list of integers denoting how digits | |
352 | of the integer part of a number are to be grouped, starting at the | |
353 | decimal point and going to the left. The list contains integers | |
354 | indicating the size of the successive groups, from right to left. If | |
355 | the list is non-circular, then no grouping occurs for digits beyond | |
356 | the last group. | |
357 | ||
358 | For instance, if the returned list is a circular list that contains | |
359 | only @code{3} and the thousand separator is @code{","} (as is the case | |
360 | with English locales), then the number @code{12345678} should be | |
361 | printed @code{12,345,678}. | |
362 | @end deffn | |
363 | ||
364 | The following procedures deal with the representation of monetary | |
365 | amounts. Some of them take an additional @var{intl?} argument (a | |
366 | boolean) that tells whether the international or local monetary | |
367 | conventions for the given locale are to be used. | |
368 | ||
369 | @deffn {Scheme Procedure} locale-monetary-decimal-point [locale] | |
370 | @deffnx {Scheme Procedure} locale-monetary-thousands-separator [locale] | |
371 | @deffnx {Scheme Procedure} locale-monetary-grouping [locale] | |
372 | These are the monetary counterparts of the above procedures. These | |
373 | procedures apply to monetary amounts. | |
374 | @end deffn | |
375 | ||
376 | @deffn {Scheme Procedure} locale-currency-symbol intl? [locale] | |
377 | Return the currency symbol (a string) of either @var{locale} or the | |
378 | current locale. | |
379 | ||
380 | The following example illustrates the difference between the local and | |
381 | international monetary formats: | |
382 | ||
383 | @example | |
384 | (define us (make-locale LC_MONETARY "en_US")) | |
385 | (locale-currency-symbol #f us) | |
386 | @result{} "-$" | |
387 | (locale-currency-symbol #t us) | |
388 | @result{} "USD " | |
389 | @end example | |
390 | @end deffn | |
391 | ||
392 | @deffn {Scheme Procedure} locale-monetary-fractional-digits intl? [locale] | |
393 | Return the number of fractional digits to be used when printing | |
394 | monetary amounts according to either @var{locale} or the current | |
395 | locale. If the locale does not specify it, then @code{#f} is | |
396 | returned. | |
397 | @end deffn | |
398 | ||
399 | @deffn {Scheme Procedure} locale-currency-symbol-precedes-positive? intl? [locale] | |
400 | @deffnx {Scheme Procedure} locale-currency-symbol-precedes-negative? intl? [locale] | |
401 | @deffnx {Scheme Procedure} locale-positive-separated-by-space? intl? [locale] | |
402 | @deffnx {Scheme Procedure} locale-negative-separated-by-space? intl? [locale] | |
403 | These procedures return a boolean indicating whether the currency | |
404 | symbol should precede a positive/negative number, and whether a | |
405 | whitespace should be inserted between the currency symbol and a | |
406 | positive/negative amount. | |
407 | @end deffn | |
408 | ||
409 | @deffn {Scheme Procedure} locale-monetary-positive-sign [locale] | |
410 | @deffnx {Scheme Procedure} locale-monetary-negative-sign [locale] | |
411 | Return a string denoting the positive (respectively negative) sign | |
412 | that should be used when printing a monetary amount. | |
413 | @end deffn | |
414 | ||
415 | @deffn {Scheme Procedure} locale-positive-sign-position | |
416 | @deffnx {Scheme Procedure} locale-negative-sign-position | |
417 | These functions return a symbol telling where a sign of a | |
418 | positive/negative monetary amount is to appear when printing it. The | |
419 | possible values are: | |
420 | ||
421 | @table @code | |
422 | @item parenthesize | |
423 | The currency symbol and quantity should be surrounded by parentheses. | |
424 | @item sign-before | |
425 | Print the sign string before the quantity and currency symbol. | |
426 | @item sign-after | |
427 | Print the sign string after the quantity and currency symbol. | |
428 | @item sign-before-currency-symbol | |
429 | Print the sign string right before the currency symbol. | |
430 | @item sign-after-currency-symbol | |
431 | Print the sign string right after the currency symbol. | |
432 | @item unspecified | |
433 | Unspecified. We recommend you print the sign after the currency | |
434 | symbol. | |
435 | @end table | |
436 | ||
437 | @end deffn | |
438 | ||
439 | Finally, the two following procedures may be helpful when programming | |
440 | user interfaces: | |
441 | ||
442 | @deffn {Scheme Procedure} locale-yes-regexp [locale] | |
443 | @deffnx {Scheme Procedure} locale-no-regexp [locale] | |
444 | Return a string that can be used as a regular expression to recognize | |
445 | a positive (respectively, negative) response to a yes/no question. | |
446 | For the C locale, the default values are typically @code{"^[yY]"} and | |
447 | @code{"^[nN]"}, respectively. | |
448 | ||
449 | Here is an example: | |
450 | ||
451 | @example | |
698307a0 | 452 | (use-modules (ice-9 rdelim)) |
a2f00b9b | 453 | (format #t "Does Guile rock?~%") |
698307a0 | 454 | (let lp ((answer (read-line))) |
a2f00b9b | 455 | (cond ((string-match (locale-yes-regexp) answer) |
698307a0 | 456 | (format #t "High fives!~%")) |
a2f00b9b | 457 | ((string-match (locale-no-regexp) answer) |
698307a0 AW |
458 | (format #t "How about now? Does it rock yet?~%") |
459 | (lp (read-line))) | |
a2f00b9b | 460 | (else |
698307a0 AW |
461 | (format #t "What do you mean?~%") |
462 | (lp (read-line))))) | |
a2f00b9b LC |
463 | @end example |
464 | ||
465 | For an internationalized yes/no string output, @code{gettext} should | |
466 | be used (@pxref{Gettext Support}). | |
467 | @end deffn | |
468 | ||
469 | Example uses of some of these functions are the implementation of the | |
470 | @code{number->locale-string} and @code{monetary-amount->locale-string} | |
471 | procedures (@pxref{Number Input and Output}), as well as that the | |
72b3aa56 | 472 | SRFI-19 date and time conversion to/from strings (@pxref{SRFI-19}). |
a2f00b9b | 473 | |
b89c4943 | 474 | |
a2f00b9b | 475 | @node Gettext Support, , Accessing Locale Information, Internationalization |
b89c4943 LC |
476 | @subsection Gettext Support |
477 | ||
09ecf78c KR |
478 | Guile provides an interface to GNU @code{gettext} for translating |
479 | message strings (@pxref{Introduction,,, gettext, GNU @code{gettext} | |
480 | utilities}). | |
481 | ||
482 | Messages are collected in domains, so different libraries and programs | |
483 | maintain different message catalogues. The @var{domain} parameter in | |
484 | the functions below is a string (it becomes part of the message | |
485 | catalog filename). | |
486 | ||
487 | When @code{gettext} is not available, or if Guile was configured | |
488 | @samp{--without-nls}, dummy functions doing no translation are | |
b89c4943 LC |
489 | provided. When @code{gettext} support is available in Guile, the |
490 | @code{i18n} feature is provided (@pxref{Feature Tracking}). | |
09ecf78c KR |
491 | |
492 | @deffn {Scheme Procedure} gettext msg [domain [category]] | |
493 | @deffnx {C Function} scm_gettext (msg, domain, category) | |
494 | Return the translation of @var{msg} in @var{domain}. @var{domain} is | |
495 | optional and defaults to the domain set through @code{textdomain} | |
496 | below. @var{category} is optional and defaults to @code{LC_MESSAGES} | |
497 | (@pxref{Locales}). | |
498 | ||
499 | Normal usage is for @var{msg} to be a literal string. | |
500 | @command{xgettext} can extract those from the source to form a message | |
501 | catalogue ready for translators (@pxref{xgettext Invocation,, Invoking | |
502 | the @command{xgettext} Program, gettext, GNU @code{gettext} | |
503 | utilities}). | |
504 | ||
505 | @example | |
506 | (display (gettext "You are in a maze of twisty passages.")) | |
507 | @end example | |
508 | ||
509 | @code{_} is a commonly used shorthand, an application can make that an | |
510 | alias for @code{gettext}. Or a library can make a definition that | |
511 | uses its specific @var{domain} (so an application can change the | |
512 | default without affecting the library). | |
513 | ||
514 | @example | |
515 | (define (_ msg) (gettext msg "mylibrary")) | |
516 | (display (_ "File not found.")) | |
517 | @end example | |
518 | ||
519 | @code{_} is also a good place to perhaps strip disambiguating extra | |
520 | text from the message string, as for instance in @ref{GUI program | |
521 | problems,, How to use @code{gettext} in GUI programs, gettext, GNU | |
522 | @code{gettext} utilities}. | |
fd936c91 MV |
523 | @end deffn |
524 | ||
09ecf78c KR |
525 | @deffn {Scheme Procedure} ngettext msg msgplural n [domain [category]] |
526 | @deffnx {C Function} scm_ngettext (msg, msgplural, n, domain, category) | |
527 | Return the translation of @var{msg}/@var{msgplural} in @var{domain}, | |
528 | with a plural form chosen appropriately for the number @var{n}. | |
529 | @var{domain} is optional and defaults to the domain set through | |
530 | @code{textdomain} below. @var{category} is optional and defaults to | |
531 | @code{LC_MESSAGES} (@pxref{Locales}). | |
532 | ||
533 | @var{msg} is the singular form, and @var{msgplural} the plural. When | |
534 | no translation is available, @var{msg} is used if @math{@var{n} = 1}, | |
535 | or @var{msgplural} otherwise. When translated, the message catalogue | |
536 | can have a different rule, and can have more than two possible forms. | |
537 | ||
538 | As per @code{gettext} above, normal usage is for @var{msg} and | |
539 | @var{msgplural} to be literal strings, since @command{xgettext} can | |
540 | extract them from the source to build a message catalogue. For | |
541 | example, | |
542 | ||
543 | @example | |
544 | (define (done n) | |
545 | (format #t (ngettext "~a file processed\n" | |
546 | "~a files processed\n" n) | |
547 | n)) | |
548 | ||
549 | (done 1) @print{} 1 file processed | |
550 | (done 3) @print{} 3 files processed | |
551 | @end example | |
552 | ||
553 | It's important to use @code{ngettext} rather than plain @code{gettext} | |
554 | for plurals, since the rules for singular and plural forms in English | |
555 | are not the same in other languages. Only @code{ngettext} will allow | |
40296bab KR |
556 | translators to give correct forms (@pxref{Plural forms,, Additional |
557 | functions for plural forms, gettext, GNU @code{gettext} utilities}). | |
fd936c91 MV |
558 | @end deffn |
559 | ||
09ecf78c KR |
560 | @deffn {Scheme Procedure} textdomain [domain] |
561 | @deffnx {C Function} scm_textdomain (domain) | |
562 | Get or set the default gettext domain. When called with no parameter | |
563 | the current domain is returned. When called with a parameter, | |
564 | @var{domain} is set as the current domain, and that new value | |
565 | returned. For example, | |
566 | ||
567 | @example | |
568 | (textdomain "myprog") | |
569 | @result{} "myprog" | |
570 | @end example | |
fd936c91 MV |
571 | @end deffn |
572 | ||
09ecf78c KR |
573 | @deffn {Scheme Procedure} bindtextdomain domain [directory] |
574 | @deffnx {C Function} scm_bindtextdomain (domain, directory) | |
575 | Get or set the directory under which to find message files for | |
576 | @var{domain}. When called without a @var{directory} the current | |
577 | setting is returned. When called with a @var{directory}, | |
578 | @var{directory} is set for @var{domain} and that new setting returned. | |
579 | For example, | |
580 | ||
581 | @example | |
582 | (bindtextdomain "myprog" "/my/tree/share/locale") | |
583 | @result{} "/my/tree/share/locale" | |
584 | @end example | |
585 | ||
586 | When using Autoconf/Automake, an application should arrange for the | |
587 | configured @code{localedir} to get into the program (by substituting, | |
588 | or by generating a config file) and set that for its domain. This | |
589 | ensures the catalogue can be found even when installed in a | |
590 | non-standard location. | |
fd936c91 MV |
591 | @end deffn |
592 | ||
09ecf78c KR |
593 | @deffn {Scheme Procedure} bind-textdomain-codeset domain [encoding] |
594 | @deffnx {C Function} scm_bind_textdomain_codeset (domain, encoding) | |
595 | Get or set the text encoding to be used by @code{gettext} for messages | |
596 | from @var{domain}. @var{encoding} is a string, the name of a coding | |
597 | system, for instance @nicode{"8859_1"}. (On a Unix/POSIX system the | |
598 | @command{iconv} program can list all available encodings.) | |
599 | ||
600 | When called without an @var{encoding} the current setting is returned, | |
601 | or @code{#f} if none yet set. When called with an @var{encoding}, it | |
602 | is set for @var{domain} and that new setting returned. For example, | |
603 | ||
604 | @example | |
605 | (bind-textdomain-codeset "myprog") | |
606 | @result{} #f | |
607 | (bind-textdomain-codeset "myprog" "latin-9") | |
608 | @result{} "latin-9" | |
609 | @end example | |
610 | ||
611 | The encoding requested can be different from the translated data file, | |
612 | messages will be recoded as necessary. But note that when there is no | |
613 | translation, @code{gettext} returns its @var{msg} unchanged, ie.@: | |
614 | without any recoding. For that reason source message strings are best | |
615 | as plain ASCII. | |
616 | ||
617 | Currently Guile has no understanding of multi-byte characters, and | |
618 | string functions won't recognise character boundaries in multi-byte | |
619 | strings. An application will at least be able to pass such strings | |
620 | through to some output though. Perhaps this will change in the | |
621 | future. | |
fd936c91 MV |
622 | @end deffn |
623 | ||
624 | @c Local Variables: | |
625 | @c TeX-master: "guile.texi" | |
b89c4943 | 626 | @c ispell-local-dictionary: "american" |
fd936c91 | 627 | @c End: |