man/lispref/internationalization.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the XEmacs Lisp Reference Manual.
   3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
   4 @c See the file lispref.texi for copying conditions.
   5 @setfilename ../../info/internationalization.info
   6 @node Internationalization, MULE, PostgreSQL Support, top
   7 @chapter Internationalization
   8
   9 @menu
  10 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
  11 * I18N Level 3::        Support for localized messages.
  12 * I18N Level 4::        Support for Asian languages.
  13 @end menu
  14
  15
  16 @node I18N Levels 1 and 2
  17 @section I18N Levels 1 and 2
  18
  19 XEmacs is now compliant with I18N levels 1 and 2.  Specifically, this means
  20 that it is 8-bit clean and correctly handles time and date functions.  XEmacs
  21 will correctly display the entire ISO-Latin 1 character set.
  22
  23 The compose key may now be used to create any character in the ISO-Latin 1
  24 character set not directly available via the keyboard..  In order for the
  25 compose key to work it is necessary to load the file @file{x-compose.el}.
  26 At any time while composing a character, @code{C-h} will display all valid
  27 completions and the character which would be produced.
  28
  29
  30 @node I18N Level 3
  31 @section I18N Level 3
  32
  33 @menu
  34 * Level 3 Basics::
  35 * Level 3 Primitives::
  36 * Dynamic Messaging::
  37 * Domain Specification::
  38 * Documentation String Extraction::
  39 @end menu
  40
  41 @node Level 3 Basics
  42 @subsection Level 3 Basics
  43
  44 XEmacs now provides alpha-level functionality for I18N Level 3.  This means
  45 that everything necessary for full messaging is available, but not every
  46 file has been converted.
  47
  48 The two message files which have been created are @file{src/emacs.po} and
  49 @file{lisp/packages/mh-e.po}.  Both files need to be converted using
  50 @code{msgfmt}, and the resulting @file{.mo} files placed in some locale's
  51 @code{LC_MESSAGES} directory.  The test ``translations'' in these files are
  52 the original messages prefixed by @code{TRNSLT_}.
  53
  54 The domain for a variable is stored on the variable's property list under
  55 the property name @var{variable-domain}.  The function
  56 @code{documentation-property} uses this information when translating a
  57 variable's documentation.
  58
  59
  60 @node Level 3 Primitives
  61 @subsection Level 3 Primitives
  62
  63 @defun gettext string
  64 This function looks up @var{string} in the default message domain and
  65 returns its translation.  If @code{I18N3} was not enabled when XEmacs was
  66 compiled, it just returns @var{string}.
  67 @end defun
  68
  69 @defun dgettext domain string
  70 This function looks up @var{string} in the specified message domain and
  71 returns its translation.  If @code{I18N3} was not enabled when XEmacs was
  72 compiled, it just returns @var{string}.
  73 @end defun
  74
  75 @defun bind-text-domain domain pathname
  76 This function associates a pathname with a message domain.
  77 Here's how the path to message file is constructed under SunOS 5.x:
  78
  79 @example
  80 @code{@{pathname@}/@{LANG@}/LC_MESSAGES/@{domain@}.mo}
  81 @end example
  82
  83 If @code{I18N3} was not enabled when XEmacs was compiled, this function does
  84 nothing.
  85 @end defun
  86
  87 @defspec domain string
  88 This function specifies the text domain used for translating documentation
  89 strings and interactive prompts of a function.  For example, write:
  90
  91 @example
  92 (defun foo (arg) "Doc string" (domain "emacs-foo") @dots{})
  93 @end example
  94
  95 to specify @code{emacs-foo} as the text domain of the function @code{foo}.
  96 The ``call'' to @code{domain} is actually a declaration rather than a
  97 function; when actually called, @code{domain} just returns @code{nil}.
  98 @end defspec
  99
 100 @defun domain-of function
 101 This function returns the text domain of @var{function}; it returns
 102 @code{nil} if it is the default domain.  If @code{I18N3} was not enabled
 103 when XEmacs was compiled, it always returns @code{nil}.
 104 @end defun
 105
 106
 107 @node Dynamic Messaging
 108 @subsection Dynamic Messaging
 109
 110 The @code{format} function has been extended to permit you to change the
 111 order of parameter insertion.  For example, the conversion format
 112 @code{%1$s} inserts parameter one as a string, while @code{%2$s} inserts
 113 parameter two.  This is useful when creating translations which require you
 114 to change the word order.
 115
 116
 117 @node Domain Specification
 118 @subsection Domain Specification
 119
 120 The default message domain of XEmacs is `emacs'.  For add-on packages, it is
 121 best to use a different domain.  For example, let us say we want to convert
 122 the ``gorilla'' package to use the domain `emacs-gorilla'.
 123 To translate the message ``What gorilla?'', use @code{dgettext} as follows:
 124
 125 @example
 126 (dgettext "emacs-gorilla" "What gorilla?")
 127 @end example
 128
 129 A function (or macro) which has a documentation string or an interactive
 130 prompt needs to be associated with the domain in order for the documentation
 131 or prompt to be translated.  This is done with the @code{domain} special
 132 form as follows:
 133
 134 @page
 135 @example
 136 (defun scratch (location)
 137   "Scratch the specified location."
 138   (domain "emacs-gorilla")
 139   (interactive "sScratch: ")
 140   @dots{} )
 141 @end example
 142
 143 It is most efficient to specify the domain in the first line of the
 144 function body, before the @code{interactive} form.
 145
 146 For variables and constants which have documentation strings, specify the
 147 domain after the documentation.
 148
 149 @defspec defvar symbol [value [doc-string [domain]]]
 150 Example:
 151 @example
 152 (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
 153 @end example
 154 @end defspec
 155
 156 @defspec defconst symbol [value [doc-string [domain]]]
 157 Example:
 158 @example
 159 (defconst limbs 4 "Number of limbs" "emacs-gorilla")
 160 @end example
 161 @end defspec
 162
 163 @defun autoload function filename &optional docstring interactive type
 164 This function defines @var{function} to autoload from @var{filename}
 165 Example:
 166 @example
 167 (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
 168 @end example
 169 @end defun
 170
 171
 172 @node Documentation String Extraction
 173 @subsection Documentation String Extraction
 174
 175 The utility @file{etc/make-po} scans the file @code{DOC} to extract
 176 documentation strings and creates a message file @code{doc.po}.  This file
 177 may then be inserted within @code{emacs.po}.
 178
 179 Currently, @code{make-po} is hard-coded to read from @code{DOC} and write
 180 to @code{doc.po}.  In order to extract documentation strings from an add-on
 181 package, first run @code{make-docfile} on the package to produce the
 182 @code{DOC} file.  Then run @code{make-po -p} with the @code{-p} argument to
 183 indicate that we are extracting documentation for an add-on package.
 184
 185 (The @code{-p} argument is a kludge to make up for a subtle difference
 186 between pre-loaded documentation and add-on documentation:  For add-on
 187 packages, the final carriage returns in the strings produced by
 188 @code{make-docfile} must be ignored.)
 189
 190 @node I18N Level 4
 191 @section I18N Level 4
 192
 193 The Asian-language support in XEmacs is called ``MULE''.  @xref{MULE}.