Mercurial > hg > xemacs-beta

comparison man/lispref/internationalization.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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, ToolTalk 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 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 Autoloaded functions which are specified in @file{loaddefs.el} do not need
164 to have a domain specification, because their documentation strings are
165 extracted into the main message base. However, for autoloaded functions
166 which are specified in a separate package, use following syntax:
167
168 @defun autoload symbol filename &optional docstring interactive macro domain
169 Example:
170 @example
171 (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
172 @end example
173 @end defun
174
175
176 @node Documentation String Extraction
177 @subsection Documentation String Extraction
178
179 The utility @file{etc/make-po} scans the file @code{DOC} to extract
180 documentation strings and creates a message file @code{doc.po}. This file
181 may then be inserted within @code{emacs.po}.
182
183 Currently, @code{make-po} is hard-coded to read from @code{DOC} and write
184 to @code{doc.po}. In order to extract documentation strings from an add-on
185 package, first run @code{make-docfile} on the package to produce the
186 @code{DOC} file. Then run @code{make-po -p} with the @code{-p} argument to
187 indicate that we are extracting documentation for an add-on package.
188
189 (The @code{-p} argument is a kludge to make up for a subtle difference
190 between pre-loaded documentation and add-on documentation: For add-on
191 packages, the final carriage returns in the strings produced by
192 @code{make-docfile} must be ignored.)
193
194 @node I18N Level 4
195 @section I18N Level 4
196
197 The Asian-language support in XEmacs is called ``MULE''. @xref{MULE}.