summaryrefslogtreecommitdiff
path: root/doc/ref/api-i18n.texi
blob: 995e27e90bbc4db1a71dab4eccaed679d897b423 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Internationalization
@section Support for Internationalization

Guile provides an interface to GNU @code{gettext} for translating
message strings (@pxref{Introduction,,, gettext, GNU @code{gettext}
utilities}).

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

When @code{gettext} is not available, or if Guile was configured
@samp{--without-nls}, dummy functions doing no translation are
provided.

@deffn {Scheme Procedure} gettext msg [domain [category]]
@deffnx {C Function} scm_gettext (msg, domain, category)
Return the translation of @var{msg} in @var{domain}.  @var{domain} is
optional and defaults to the domain set through @code{textdomain}
below.  @var{category} is optional and defaults to @code{LC_MESSAGES}
(@pxref{Locales}).

Normal usage is for @var{msg} to be a literal string.
@command{xgettext} can extract those from the source to form a message
catalogue ready for translators (@pxref{xgettext Invocation,, Invoking
the @command{xgettext} Program, gettext, GNU @code{gettext}
utilities}).

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

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

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

@code{_} is also a good place to perhaps strip disambiguating extra
text from the message string, as for instance in @ref{GUI program
problems,, How to use @code{gettext} in GUI programs, gettext, GNU
@code{gettext} utilities}.
@end deffn

@deffn {Scheme Procedure} ngettext msg msgplural n [domain [category]]
@deffnx {C Function} scm_ngettext (msg, msgplural, n, domain, category)
Return the translation of @var{msg}/@var{msgplural} in @var{domain},
with a plural form chosen appropriately for the number @var{n}.
@var{domain} is optional and defaults to the domain set through
@code{textdomain} below.  @var{category} is optional and defaults to
@code{LC_MESSAGES} (@pxref{Locales}).

@var{msg} is the singular form, and @var{msgplural} the plural.  When
no translation is available, @var{msg} is used if @math{@var{n} = 1},
or @var{msgplural} otherwise.  When translated, the message catalogue
can have a different rule, and can have more than two possible forms.

As per @code{gettext} above, normal usage is for @var{msg} and
@var{msgplural} to be literal strings, since @command{xgettext} can
extract them from the source to build a message catalogue.  For
example,

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

(done 1) @print{} 1 file processed
(done 3) @print{} 3 files processed
@end example

It's important to use @code{ngettext} rather than plain @code{gettext}
for plurals, since the rules for singular and plural forms in English
are not the same in other languages.  Only @code{ngettext} will allow
translators to give correct forms.
@end deffn

@deffn {Scheme Procedure} textdomain [domain]
@deffnx {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,
@var{domain} is set as the current domain, and that new value
returned.  For example,

@example
(textdomain "myprog")
@result{} "myprog"
@end example
@end deffn

@deffn {Scheme Procedure} bindtextdomain domain [directory]
@deffnx {C Function} scm_bindtextdomain (domain, directory)
Get or set the directory under which to find message files for
@var{domain}.  When called without a @var{directory} the current
setting is returned.  When called with a @var{directory},
@var{directory} is set for @var{domain} and that new setting returned.
For example,

@example
(bindtextdomain "myprog" "/my/tree/share/locale")
@result{} "/my/tree/share/locale"
@end example

When using Autoconf/Automake, an application should arrange for the
configured @code{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.
@end deffn

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

When called without an @var{encoding} the current setting is returned,
or @code{#f} if none yet set.  When called with an @var{encoding}, it
is set for @var{domain} and that new setting returned.  For example,

@example
(bind-textdomain-codeset "myprog")
@result{} #f
(bind-textdomain-codeset "myprog" "latin-9")
@result{} "latin-9"
@end example

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, @code{gettext} returns its @var{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.
@end deffn

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: