cgit.sxemacs.org Git - sxemacs/blob - info/lispref/internationalization.texi

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