| 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, 2006, 2007, 2009, 2010 |
| 4 | @c Free Software Foundation, Inc. |
| 5 | @c See the file guile.texi for copying conditions. |
| 6 | |
| 7 | @node Internationalization |
| 8 | @section Support for Internationalization |
| 9 | |
| 10 | @cindex internationalization |
| 11 | @cindex i18n |
| 12 | |
| 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. |
| 20 | |
| 21 | @menu |
| 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. |
| 28 | @end menu |
| 29 | |
| 30 | |
| 31 | @node i18n Introduction, Text Collation, Internationalization, Internationalization |
| 32 | @subsection Internationalization with Guile |
| 33 | |
| 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: |
| 36 | |
| 37 | @example |
| 38 | (use-modules (ice-9 i18n)) |
| 39 | @end example |
| 40 | |
| 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 |
| 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}}). |
| 70 | |
| 71 | The following procedures allow the manipulation of such locale |
| 72 | objects. |
| 73 | |
| 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) |
| 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 |
| 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): |
| 89 | |
| 90 | @example |
| 91 | (make-locale (list LC_MESSAGES LC_CTYPE) "sv_SE") |
| 92 | @end example |
| 93 | |
| 94 | The following example combines the use of Esperanto messages and |
| 95 | conventions with monetary conventions from Croatia: |
| 96 | |
| 97 | @example |
| 98 | (make-locale LC_MONETARY "hr_HR" |
| 99 | (make-locale LC_ALL "eo_EO")) |
| 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 | |
| 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. |
| 128 | |
| 129 | @deffn {Scheme Procedure} string-locale<? s1 s2 [locale] |
| 130 | @deffnx {C Function} scm_string_locale_lt (s1, s2, locale) |
| 131 | @deffnx {Scheme Procedure} string-locale>? s1 s2 [locale] |
| 132 | @deffnx {C Function} scm_string_locale_gt (s1, s2, locale) |
| 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) |
| 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; |
| 140 | otherwise, the current system locale is used. For the @code{-ci} |
| 141 | variants, the comparison is made in a case-insensitive way. |
| 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 |
| 148 | a locale object (as returned by @code{make-locale}) and will be used to |
| 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) |
| 154 | @deffnx {Scheme Procedure} char-locale>? c1 c2 [locale] |
| 155 | @deffnx {C Function} scm_char_locale_gt (c1, c2, locale) |
| 156 | @deffnx {Scheme Procedure} char-locale-ci<? c1 c2 [locale] |
| 157 | @deffnx {C Function} scm_char_locale_ci_lt (c1, c2, locale) |
| 158 | @deffnx {Scheme Procedure} char-locale-ci>? c1 c2 [locale] |
| 159 | @deffnx {C Function} scm_char_locale_ci_gt (c1, c2, locale) |
| 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. |
| 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 | |
| 172 | @node Character Case Mapping, Number Input and Output, Text Collation, Internationalization |
| 173 | @subsection Character Case Mapping |
| 174 | |
| 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 |
| 184 | above''. The following procedures allow programmers to provide |
| 185 | idiomatic character mapping. |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 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 |
| 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 |
| 229 | in French it is written @code{10 000,5}. These procedures allow such |
| 230 | differences to be taken into account. |
| 231 | |
| 232 | @findex strtod |
| 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, |
| 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}). |
| 247 | @end deffn |
| 248 | |
| 249 | @findex strtod |
| 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 |
| 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. |
| 339 | @end deffn |
| 340 | |
| 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 |
| 452 | (use-modules (ice-9 rdelim)) |
| 453 | (format #t "Does Guile rock?~%") |
| 454 | (let lp ((answer (read-line))) |
| 455 | (cond ((string-match (locale-yes-regexp) answer) |
| 456 | (format #t "High fives!~%")) |
| 457 | ((string-match (locale-no-regexp) answer) |
| 458 | (format #t "How about now? Does it rock yet?~%") |
| 459 | (lp (read-line))) |
| 460 | (else |
| 461 | (format #t "What do you mean?~%") |
| 462 | (lp (read-line))))) |
| 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 |
| 472 | SRFI-19 date and time conversion to/from strings (@pxref{SRFI-19}). |
| 473 | |
| 474 | |
| 475 | @node Gettext Support, , Accessing Locale Information, Internationalization |
| 476 | @subsection Gettext Support |
| 477 | |
| 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 |
| 489 | provided. When @code{gettext} support is available in Guile, the |
| 490 | @code{i18n} feature is provided (@pxref{Feature Tracking}). |
| 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}. |
| 523 | @end deffn |
| 524 | |
| 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 |
| 556 | translators to give correct forms (@pxref{Plural forms,, Additional |
| 557 | functions for plural forms, gettext, GNU @code{gettext} utilities}). |
| 558 | @end deffn |
| 559 | |
| 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 |
| 571 | @end deffn |
| 572 | |
| 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. |
| 591 | @end deffn |
| 592 | |
| 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. |
| 622 | @end deffn |
| 623 | |
| 624 | @c Local Variables: |
| 625 | @c TeX-master: "guile.texi" |
| 626 | @c ispell-local-dictionary: "american" |
| 627 | @c End: |