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