summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKevin Ryde <user42@zip.com.au>2005-01-23 23:22:36 +0000
committerKevin Ryde <user42@zip.com.au>2005-01-23 23:22:36 +0000
commit09ecf78c60c47fb5771c740d4fd2bf70b0fad9fd (patch)
treeacab1c5ff7d32c34bfb8436e8cda55d735d0647a
parent333db3b87f244f3c18a9bc86370690d91cf7bbeb (diff)
downloadguile-09ecf78c60c47fb5771c740d4fd2bf70b0fad9fd.tar.gz
(Internationalization): Expand and revise a bit for clarity.
-rw-r--r--doc/ref/api-i18n.texi153
1 files changed, 134 insertions, 19 deletions
diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi
index 7ed4fae7f..995e27e90 100644
--- a/doc/ref/api-i18n.texi
+++ b/doc/ref/api-i18n.texi
@@ -8,33 +8,148 @@
@node Internationalization
@section Support for Internationalization
-@deffn {Scheme Procedure} gettext msgid [domain [category]]
-@deffnx {C Function} scm_gettext (msgid, domain, category)
-Return the translation of @var{msgid} in the message domain @var{domain}. @var{domain} is optional and defaults to the domain set through (textdomain). @var{category} is optional and defaults to LC_MESSAGES.
+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 msgid msgid_plural n [domain [category]]
-@deffnx {C Function} scm_ngettext (msgid, msgid_plural, n, domain, category)
-Return the translation of @var{msgid}/@var{msgid_plural} in the message domain @var{domain}, with the plural form being chosen appropriately for the number @var{n}. @var{domain} is optional and defaults to the domain set through (textdomain). @var{category} is optional and defaults to LC_MESSAGES.
+@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 [domainname]
-@deffnx {C Function} scm_textdomain (domainname)
-If optional parameter @var{domainname} is supplied, set the textdomain. Return the textdomain.
+@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 domainname [directory]
-@deffnx {C Function} scm_bindtextdomain (domainname, directory)
-If optional parameter @var{directory} is supplied, set message
-catalogs to directory @var{directory}. Return the directory bound to
-@var{domainname}.
+@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 domainname [encoding]
-@deffnx {C Function} scm_bind_textdomain_codeset (domainname, encoding)
-If optional parameter @var{encoding} is supplied, set encoding for
-message catalogs of @var{domainname}. Return the encoding of
-@var{domainname}.
+@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: