guile18/doc/ref/api-i18n.texi

   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
   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
  11 Guile provides an interface to GNU @code{gettext} for translating
  12 message strings (@pxref{Introduction,,, gettext, GNU @code{gettext}
  13 utilities}).
  14
  15 Messages are collected in domains, so different libraries and programs
  16 maintain different message catalogues.  The @var{domain} parameter in
  17 the functions below is a string (it becomes part of the message
  18 catalog filename).
  19
  20 When @code{gettext} is not available, or if Guile was configured
  21 @samp{--without-nls}, dummy functions doing no translation are
  22 provided.
  23
  24 @deffn {Scheme Procedure} gettext msg [domain [category]]
  25 @deffnx {C Function} scm_gettext (msg, domain, category)
  26 Return the translation of @var{msg} in @var{domain}.  @var{domain} is
  27 optional and defaults to the domain set through @code{textdomain}
  28 below.  @var{category} is optional and defaults to @code{LC_MESSAGES}
  29 (@pxref{Locales}).
  30
  31 Normal usage is for @var{msg} to be a literal string.
  32 @command{xgettext} can extract those from the source to form a message
  33 catalogue ready for translators (@pxref{xgettext Invocation,, Invoking
  34 the @command{xgettext} Program, gettext, GNU @code{gettext}
  35 utilities}).
  36
  37 @example
  38 (display (gettext "You are in a maze of twisty passages."))
  39 @end example
  40
  41 @code{_} is a commonly used shorthand, an application can make that an
  42 alias for @code{gettext}.  Or a library can make a definition that
  43 uses its specific @var{domain} (so an application can change the
  44 default without affecting the library).
  45
  46 @example
  47 (define (_ msg) (gettext msg "mylibrary"))
  48 (display (_ "File not found."))
  49 @end example
  50
  51 @code{_} is also a good place to perhaps strip disambiguating extra
  52 text from the message string, as for instance in @ref{GUI program
  53 problems,, How to use @code{gettext} in GUI programs, gettext, GNU
  54 @code{gettext} utilities}.
  55 @end deffn
  56
  57 @deffn {Scheme Procedure} ngettext msg msgplural n [domain [category]]
  58 @deffnx {C Function} scm_ngettext (msg, msgplural, n, domain, category)
  59 Return the translation of @var{msg}/@var{msgplural} in @var{domain},
  60 with a plural form chosen appropriately for the number @var{n}.
  61 @var{domain} is optional and defaults to the domain set through
  62 @code{textdomain} below.  @var{category} is optional and defaults to
  63 @code{LC_MESSAGES} (@pxref{Locales}).
  64
  65 @var{msg} is the singular form, and @var{msgplural} the plural.  When
  66 no translation is available, @var{msg} is used if @math{@var{n} = 1},
  67 or @var{msgplural} otherwise.  When translated, the message catalogue
  68 can have a different rule, and can have more than two possible forms.
  69
  70 As per @code{gettext} above, normal usage is for @var{msg} and
  71 @var{msgplural} to be literal strings, since @command{xgettext} can
  72 extract them from the source to build a message catalogue.  For
  73 example,
  74
  75 @example
  76 (define (done n)
  77   (format #t (ngettext "~a file processed\n"
  78                        "~a files processed\n" n)
  79              n))
  80
  81 (done 1) @print{} 1 file processed
  82 (done 3) @print{} 3 files processed
  83 @end example
  84
  85 It's important to use @code{ngettext} rather than plain @code{gettext}
  86 for plurals, since the rules for singular and plural forms in English
  87 are not the same in other languages.  Only @code{ngettext} will allow
  88 translators to give correct forms (@pxref{Plural forms,, Additional
  89 functions for plural forms, gettext, GNU @code{gettext} utilities}).
  90 @end deffn
  91
  92 @deffn {Scheme Procedure} textdomain [domain]
  93 @deffnx {C Function} scm_textdomain (domain)
  94 Get or set the default gettext domain.  When called with no parameter
  95 the current domain is returned.  When called with a parameter,
  96 @var{domain} is set as the current domain, and that new value
  97 returned.  For example,
  98
  99 @example
 100 (textdomain "myprog")
 101 @result{} "myprog"
 102 @end example
 103 @end deffn
 104
 105 @deffn {Scheme Procedure} bindtextdomain domain [directory]
 106 @deffnx {C Function} scm_bindtextdomain (domain, directory)
 107 Get or set the directory under which to find message files for
 108 @var{domain}.  When called without a @var{directory} the current
 109 setting is returned.  When called with a @var{directory},
 110 @var{directory} is set for @var{domain} and that new setting returned.
 111 For example,
 112
 113 @example
 114 (bindtextdomain "myprog" "/my/tree/share/locale")
 115 @result{} "/my/tree/share/locale"
 116 @end example
 117
 118 When using Autoconf/Automake, an application should arrange for the
 119 configured @code{localedir} to get into the program (by substituting,
 120 or by generating a config file) and set that for its domain.  This
 121 ensures the catalogue can be found even when installed in a
 122 non-standard location.
 123 @end deffn
 124
 125 @deffn {Scheme Procedure} bind-textdomain-codeset domain [encoding]
 126 @deffnx {C Function} scm_bind_textdomain_codeset (domain, encoding)
 127 Get or set the text encoding to be used by @code{gettext} for messages
 128 from @var{domain}.  @var{encoding} is a string, the name of a coding
 129 system, for instance @nicode{"8859_1"}.  (On a Unix/POSIX system the
 130 @command{iconv} program can list all available encodings.)
 131
 132 When called without an @var{encoding} the current setting is returned,
 133 or @code{#f} if none yet set.  When called with an @var{encoding}, it
 134 is set for @var{domain} and that new setting returned.  For example,
 135
 136 @example
 137 (bind-textdomain-codeset "myprog")
 138 @result{} #f
 139 (bind-textdomain-codeset "myprog" "latin-9")
 140 @result{} "latin-9"
 141 @end example
 142
 143 The encoding requested can be different from the translated data file,
 144 messages will be recoded as necessary.  But note that when there is no
 145 translation, @code{gettext} returns its @var{msg} unchanged, ie.@:
 146 without any recoding.  For that reason source message strings are best
 147 as plain ASCII.
 148
 149 Currently Guile has no understanding of multi-byte characters, and
 150 string functions won't recognise character boundaries in multi-byte
 151 strings.  An application will at least be able to pass such strings
 152 through to some output though.  Perhaps this will change in the
 153 future.
 154 @end deffn
 155
 156 @c Local Variables:
 157 @c TeX-master: "guile.texi"
 158 @c End: