Support for Internationalization
================================

Guile provides internationalization support for Scheme programs in two ways.  First, procedures to manipulate text and data in a way that conforms to particular cultural conventions (i.e., in a ``locale-dependent'' way) are provided in the (ice-9 i18n). Second, Guile allows the use of GNU gettext to translate program message strings.

The (ice-9 i18n) Module
-----------------------

In order to make use of the following functions, one must import the (ice-9 i18n) module in the usual way:

     (use-modules (ice-9 i18n))

C programs can use the C functions corresponding to the procedures of this module by including <libguile/i18n.h> and by linking against libguile-i18n-v-LIBGUILE_I18N_MAJOR.

The (ice-9 i18n) module provides procedures to manipulate text and other data in a way that conforms to the cultural conventions chosen by the user.  Each region of the world or language has its own customs to, for instance, represent real numbers, classify characters, collate text, etc.  All these aspects comprise the so-called ``cultural conventions'' of that region or language.

Computer systems typically refer to a set of cultural conventions as a locale.  For each particular aspect that comprise those cultural conventions, a locale category is defined.  For instance, the way characters are classified is defined by the LC_CTYPE category, while the language in which program messages are issued to the user is defined by the LC_MESSAGES category (see General Locale Information for details).

The procedures provided by this module allow the development of programs that adapt automatically to any locale setting.  As we will see later, many of the locale-dependent procedures provided by this module can optionally take a locale object argument.  This additional argument defines the locale settings that must be followed by the invoked procedure.  When it is omitted, then the current locale settings of the process are followed (see setlocale).

The following procedures allow the manipulation of such locale objects.

 -- Scheme Procedure: make-locale category-mask locale-name [base-locale]
 -- C Function: scm_make_locale (category_mask, locale_name, base_locale)
     Return a reference to a data structure representing a set of locale datasets.  LOCALE-NAME should be a string denoting a particular locale, e.g., "aa_DJ".  Unlike for the CATEGORY parameter for setlocale, the CATEGORY-MASK parameter here uses a single bit for each category, made by OR'ing together LC_*_MASK bits.  The optional BASE-LOCALE argument can be used to specify a locale object whose settings are to be used as a basis for the locale object being returned.

     The available locale category masks are the following:

      -- Variable: LC_COLLATE_MASK
          Represents the collation locale category.

      -- Variable: LC_CTYPE_MASK
          Represents the character classification locale category.

      -- Variable: LC_MESSAGES_MASK
          Represents the messages locale category.

      -- Variable: LC_MONETARY_MASK
          Represents the monetary locale category.

      -- Variable: LC_NUMERIC_MASK
          Represents the way numbers are displayed.

      -- Variable: LC_TIME_MASK
          Represents the way date and time are displayed

     The following category masks are also available but will not have any effect on systems that do not support them:

      -- Variable: LC_PAPER_MASK
      -- Variable: LC_NAME_MASK
      -- Variable: LC_ADDRESS_MASK
      -- Variable: LC_TELEPHONE_MASK
      -- Variable: LC_MEASUREMENT_MASK
      -- Variable: LC_IDENTIFICATION_MASK

     Finally, there is also:

      -- Variable: LC_ALL_MASK
          This represents all the locale categories supported by the system.

     The LC_*_MASK variables are bound to integers which may be OR'd together using logior (see logior).  For instance, the following invocation creates a locale object that combines the use of Esperanto for messages and character classification with the default settings for the other categories (i.e., the settings of the default C locale which usually represents conventions in use in the USA):

          (make-locale (logior LC_MESSAGE_MASK LC_CTYPE_MASK) "eo_EO")

     The following example combines the use of Swedish conventions with monetary conventions from Croatia:

          (make-locale LC_MONETARY_MASK "hr_HR"
                       (make-locale LC_ALL_MASK "sv_SE"))

     A system-error exception (see Handling Errors) is raised by make-locale when LOCALE-NAME does not match any of the locales compiled on the system.  Note that on non-GNU systems, this error may be raised later, when the locale object is actually used.

 -- Scheme Procedure: locale? obj
 -- C Function: scm_locale_p (obj)
     Return true if OBJ is a locale object.

The following procedures provide support for text collation.

 -- Scheme Procedure: string-locale<? s1 s2 [locale]
 -- C Function: scm_string_locale_lt (s1, s2, locale)
     Compare strings S1 and S2 in a locale-dependent way.  If LOCALE is provided, it should be locale object (as returned by make-locale) and will be used to perform the comparison; otherwise, the current system locale is used.

 -- Scheme Procedure: string-locale>? s1 s2 [locale]
 -- C Function: scm_string_locale_gt (s1, s2, locale)
     Compare strings S1 and S2 in a locale-dependent way.  If LOCALE is provided, it should be locale object (as returned by make-locale) and will be used to perform the comparison; otherwise, the current system locale is used.

 -- Scheme Procedure: string-locale-ci<? s1 s2 [locale]
 -- C Function: scm_string_locale_ci_lt (s1, s2, locale)
     Compare strings S1 and S2 in a case-insensitive, and locale-dependent way.  If LOCALE is provided, it should be locale object (as returned by make-locale) and will be used to perform the comparison; otherwise, the current system locale is used.

 -- Scheme Procedure: string-locale-ci>? s1 s2 [locale]
 -- C Function: scm_string_locale_ci_gt (s1, s2, locale)
     Compare strings S1 and S2 in a case-insensitive, and locale-dependent way.  If LOCALE is provided, it should be locale object (as returned by make-locale) and will be used to perform the comparison; otherwise, the current system locale is used.

 -- Scheme Procedure: string-locale-ci=? s1 s2 [locale]
 -- C Function: scm_string_locale_ci_eq (s1, s2, locale)
     Compare strings S1 and S2 in a case-insensitive, and locale-dependent way.  If LOCALE is provided, it should be locale object (as returned by make-locale) and will be used to perform the comparison; otherwise, the current system locale is used.

 -- Scheme Procedure: char-locale<? c1 c2 [locale]
 -- C Function: scm_char_locale_lt (c1, c2, locale)
     Return true if character C1 is lower than C2 according to LOCALE or to the current locale.

 -- Scheme Procedure: char-locale>? c1 c2 [locale]
 -- C Function: scm_char_locale_gt (c1, c2, locale)
     Return true if character C1 is greater than C2 according to LOCALE or to the current locale.

 -- Scheme Procedure: char-locale-ci<? c1 c2 [locale]
 -- C Function: scm_char_locale_ci_lt (c1, c2, locale)
     Return true if character C1 is lower than C2, in a case insensitive way according to LOCALE or to the current locale.

 -- Scheme Procedure: char-locale-ci>? c1 c2 [locale]
 -- C Function: scm_char_locale_ci_gt (c1, c2, locale)
     Return true if character C1 is greater than C2, in a case insensitive way according to LOCALE or to the current locale.

 -- Scheme Procedure: char-locale-ci=? c1 c2 [locale]
 -- C Function: scm_char_locale_ci_eq (c1, c2, locale)
     Return true if character C1 is equal to C2, in a case insensitive way according to LOCALE or to the current locale.

The procedures below provide support for ``character case mapping'', i.e., to convert characters or strings to their upper-case or lower-case equivalent.  Note that SRFI-13 provides procedures that look similar (see Alphabetic Case Mapping).  However, the SRFI-13 procedures are locale-independent.  Therefore, they do not take into account specificities of the customs in use in a particular language or region of the world.  For instance, while most languages using the Latin alphabet map lower-case letter ``i'' to upper-case letter ``I'', Turkish maps lower-case ``i'' to ``Latin capital letter I with dot above''.  The following procedures allow to provide idiomatic character mapping.

 -- Scheme Procedure: char-locale-downcase chr [locale]
 -- C Function: scm_char_locale_upcase (chr, locale)
     Return the lowercase character that corresponds to CHR according to either LOCALE or the current locale.

 -- Scheme Procedure: char-locale-upcase chr [locale]
 -- C Function: scm_char_locale_downcase (chr, locale)
     Return the uppercase character that corresponds to CHR according to either LOCALE or the current locale.

 -- Scheme Procedure: string-locale-upcase str [locale]
 -- C Function: scm_string_locale_upcase (str, locale)
     Return a new string that is the uppercase version of STR according to either LOCALE or the current locale.

 -- Scheme Procedure: string-locale-downcase str [locale]
 -- C Function: scm_string_locale_downcase (str, locale)
     Return a new string that is the down-case version of STR according to either LOCALE or the current locale.

Finally, the following procedures allow programs to read numbers written according to a particular locale.  As an example, in English, ``ten thousand and a half'' is usually written 10,000.5 while in French it is written 10000,5.  These procedures allow to account for these differences.

 -- Scheme Procedure: locale-string->integer str [base [locale]]
 -- C Function: scm_locale_string_to_integer (str, base, locale)
     Convert string STR into an integer according to either LOCALE (a locale object as returned by make-locale) or the current process locale.  If BASE is specified, then it determines the base of the integer being read (e.g., 16 for an hexadecimal number, 10 for a decimal number); by default, decimal numbers are read.  Return two values: an integer (on success) or #f, and the number of characters read from STR (0 on failure).

 -- Scheme Procedure: locale-string->inexact str [locale]
 -- C Function: scm_locale_string_to_inexact (str, locale)
     Convert string STR into an inexact number according to either LOCALE (a locale object as returned by make-locale) or the current process locale.  Return two values: an inexact number (on success) or #f, and the number of characters read from STR (0 on failure).

Gettext Support
---------------

Guile provides an interface to GNU gettext for translating message strings (see Introduction (GNU gettext utilities)).

Messages are collected in domains, so different libraries and programs maintain different message catalogues.  The DOMAIN parameter in the functions below is a string (it becomes part of the message catalog filename).

When gettext is not available, or if Guile was configured --without-nls, dummy functions doing no translation are provided.  When gettext support is available in Guile, the i18n feature is provided (see Feature Tracking).

 -- Scheme Procedure: gettext msg [domain [category]]
 -- C Function: scm_gettext (msg, domain, category)
     Return the translation of MSG in DOMAIN.  DOMAIN is optional and defaults to the domain set through textdomain below.  CATEGORY is optional and defaults to LC_MESSAGES (see Locales).

     Normal usage is for MSG to be a literal string. xgettext can extract those from the source to form a message catalogue ready for translators (see Invoking the xgettext Program (GNU gettext utilities)).

          (display (gettext "You are in a maze of twisty passages."))

     _ is a commonly used shorthand, an application can make that an alias for gettext.  Or a library can make a definition that uses its specific DOMAIN (so an application can change the default without affecting the library).

          (define (_ msg) (gettext msg "mylibrary"))
          (display (_ "File not found."))

     _ is also a good place to perhaps strip disambiguating extra text from the message string, as for instance in How to use gettext in GUI programs (GNU gettext utilities).

 -- Scheme Procedure: ngettext msg msgplural n [domain [category]]
 -- C Function: scm_ngettext (msg, msgplural, n, domain, category)
     Return the translation of MSG/MSGPLURAL in DOMAIN, with a plural form chosen appropriately for the number N. DOMAIN is optional and defaults to the domain set through textdomain below.  CATEGORY is optional and defaults to LC_MESSAGES (see Locales).

     MSG is the singular form, and MSGPLURAL the plural.  When no translation is available, MSG is used if N = 1, or MSGPLURAL otherwise.  When translated, the message catalogue can have a different rule, and can have more than two possible forms.

     As per gettext above, normal usage is for MSG and MSGPLURAL to be literal strings, since xgettext can extract them from the source to build a message catalogue.  For example,

          (define (done n)
            (format #t (ngettext "~a file processed\n"
                                 "~a files processed\n" n)
                       n))

          (done 1) -| 1 file processed
          (done 3) -| 3 files processed

     It's important to use ngettext rather than plain gettext for plurals, since the rules for singular and plural forms in English are not the same in other languages.  Only ngettext will allow translators to give correct forms (see Additional functions for plural forms (GNU gettext utilities)).

 -- Scheme Procedure: textdomain [domain]
 -- C Function: scm_textdomain (domain)
     Get or set the default gettext domain.  When called with no parameter the current domain is returned.  When called with a parameter, DOMAIN is set as the current domain, and that new value returned.  For example,

          (textdomain "myprog")
          => "myprog"

 -- Scheme Procedure: bindtextdomain domain [directory]
 -- C Function: scm_bindtextdomain (domain, directory)
     Get or set the directory under which to find message files for DOMAIN.  When called without a DIRECTORY the current setting is returned.  When called with a DIRECTORY, DIRECTORY is set for DOMAIN and that new setting returned. For example,

          (bindtextdomain "myprog" "/my/tree/share/locale")
          => "/my/tree/share/locale"

     When using Autoconf/Automake, an application should arrange for the configured localedir to get into the program (by substituting, or by generating a config file) and set that for its domain.  This ensures the catalogue can be found even when installed in a non-standard location.

 -- Scheme Procedure: bind-textdomain-codeset domain [encoding]
 -- C Function: scm_bind_textdomain_codeset (domain, encoding)
     Get or set the text encoding to be used by gettext for messages from DOMAIN.  ENCODING is a string, the name of a coding system, for instance "8859_1".  (On a Unix/POSIX system the iconv program can list all available encodings.)

     When called without an ENCODING the current setting is returned, or #f if none yet set.  When called with an ENCODING, it is set for DOMAIN and that new setting returned.  For example,

          (bind-textdomain-codeset "myprog")
          => #f
          (bind-textdomain-codeset "myprog" "latin-9")
          => "latin-9"

     The encoding requested can be different from the translated data file, messages will be recoded as necessary.  But note that when there is no translation, gettext returns its MSG unchanged, ie. without any recoding.  For that reason source message strings are best as plain ASCII.

     Currently Guile has no understanding of multi-byte characters, and string functions won't recognise character boundaries in multi-byte strings.  An application will at least be able to pass such strings through to some output though.  Perhaps this will change in the future.