Internationalization
********************

I18N Levels 1 and 2
===================

XEmacs is now compliant with I18N levels 1 and 2.  Specifically, this means that it is 8-bit clean and correctly handles time and date functions.  XEmacs will correctly display the entire ISO-Latin 1 character set.

The compose key may now be used to create any character in the ISO-Latin 1 character set not directly available via the keyboard..  In order for the compose key to work it is necessary to load the file x-compose.el. At any time while composing a character, C-h will display all valid completions and the character which would be produced.

I18N Level 3
============

Level 3 Basics
--------------

XEmacs now provides alpha-level functionality for I18N Level 3.  This means that everything necessary for full messaging is available, but not every file has been converted.

The two message files which have been created are src/emacs.po and lisp/packages/mh-e.po.  Both files need to be converted using msgfmt, and the resulting .mo files placed in some locale's LC_MESSAGES directory.  The test ``translations'' in these files are the original messages prefixed by TRNSLT_.

The domain for a variable is stored on the variable's property list under the property name VARIABLE-DOMAIN.  The function documentation-property uses this information when translating a variable's documentation.

Level 3 Primitives
------------------

 -- Function: gettext string
     This function looks up STRING in the default message domain and returns its translation.  If I18N3 was not enabled when XEmacs was compiled, it just returns STRING.

 -- Function: dgettext domain string
     This function looks up STRING in the specified message domain and returns its translation.  If I18N3 was not enabled when XEmacs was compiled, it just returns STRING.

 -- Function: bind-text-domain domain pathname
     This function associates a pathname with a message domain. Here's how the path to message file is constructed under SunOS 5.x:

          {pathname}/{LANG}/LC_MESSAGES/{domain}.mo

     If I18N3 was not enabled when XEmacs was compiled, this function does nothing.

 -- Special Form: domain string
     This function specifies the text domain used for translating documentation strings and interactive prompts of a function.  For example, write:

          (defun foo (arg) "Doc string" (domain "emacs-foo") ...)

     to specify emacs-foo as the text domain of the function foo. The ``call'' to domain is actually a declaration rather than a function; when actually called, domain just returns nil.

 -- Function: domain-of function
     This function returns the text domain of FUNCTION; it returns nil if it is the default domain.  If I18N3 was not enabled when XEmacs was compiled, it always returns nil.

Dynamic Messaging
-----------------

The format function has been extended to permit you to change the order of parameter insertion.  For example, the conversion format %1$s inserts parameter one as a string, while %2$s inserts parameter two.  This is useful when creating translations which require you to change the word order.

Domain Specification
--------------------

The default message domain of XEmacs is `emacs'.  For add-on packages, it is best to use a different domain.  For example, let us say we want to convert the ``gorilla'' package to use the domain `emacs-gorilla'. To translate the message ``What gorilla?'', use dgettext as follows:

     (dgettext "emacs-gorilla" "What gorilla?")

A function (or macro) which has a documentation string or an interactive prompt needs to be associated with the domain in order for the documentation or prompt to be translated.  This is done with the domain special form as follows:

     (defun scratch (location)
       "Scratch the specified location."
       (domain "emacs-gorilla")
       (interactive "sScratch: ")
       ... )

It is most efficient to specify the domain in the first line of the function body, before the interactive form.

For variables and constants which have documentation strings, specify the domain after the documentation.

 -- Special Form: defvar symbol [value [doc-string [domain]]]
     Example:

          (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")

 -- Special Form: defconst symbol [value [doc-string [domain]]]
     Example:

          (defconst limbs 4 "Number of limbs" "emacs-gorilla")

 -- Function: autoload function filename &optional docstring interactive type
     This function defines FUNCTION to autoload from FILENAME Example:

          (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")

Documentation String Extraction
-------------------------------

The utility etc/make-po scans the file DOC to extract documentation strings and creates a message file doc.po.  This file may then be inserted within emacs.po.

Currently, make-po is hard-coded to read from DOC and write to doc.po.  In order to extract documentation strings from an add-on package, first run make-docfile on the package to produce the DOC file.  Then run make-po -p with the -p argument to indicate that we are extracting documentation for an add-on package.

(The -p argument is a kludge to make up for a subtle difference between pre-loaded documentation and add-on documentation:  For add-on packages, the final carriage returns in the strings produced by make-docfile must be ignored.)

I18N Level 4
============

The Asian-language support in XEmacs is called ``MULE''.  See MULE.