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