The DOMAIN is a string identifier denoting the program that is requesting the translation. The pathname of the message catalog depends on the DOMAIN: usually it is located at TEXTDOMAINDIR/l/LC_MESSAGES/domain.mo, where l is the ISO 639-2 code of the language. The notion of DOMAIN allows several Lisp programs running in the same image to request translations independently of each other.

Function I18N:TEXTDOMAIN. (I18N:TEXTDOMAIN) is a place that returns the default DOMAIN, used when no DOMAIN argument is passed to the I18N:GETTEXT and I18N:NGETTEXT functions. It is SETFable. (SETF I18N:TEXTDOMAIN) is usually used during the startup phase of a program. Note that the default DOMAIN is not saved in a memory image. The use of (SETF I18N:TEXTDOMAIN) is recommended only for programs that are so simple that they will never need more than one DOMAIN.

Function I18N:TEXTDOMAINDIR. (I18N:TEXTDOMAINDIR DOMAIN) is a place that returns the base directory, called TEXTDOMAINDIR above, where the message catalogs for the given DOMAIN are assumed to be installed. It is SETFable. (SETF I18N:TEXTDOMAINDIR) is usually used during the startup phase of a program, and should be used because only the program knows where its message catalogs are installed. Note that the TEXTDOMAINDIRs are not saved in a memory image.

The CATEGORY argument of the I18N:GETTEXT and I18N:NGETTEXT functions denotes which LOCALE facet the result should depend on. The possible values are a platform-dependent subset of :LC_ADDRESS, :LC_ALL, :LC_COLLATE, :LC_CTYPE, :LC_IDENTIFICATION, :LC_MEASUREMENT, :LC_MESSAGES, :LC_MONETARY, :LC_NAME, :LC_NUMERIC, :LC_PAPER, :LC_TELEPHONE, :LC_TIME The use of these values is useful for users who have a character/time/collation/money handling set differently from the usual message handling. Note that when a CATEGORY argument is used, the message catalog location depends on the CATEGORY: it will be expected at TEXTDOMAINDIR/ll/category/domain.mo.

A non-internationalized program simulating a restaurant dialogue might look as follows.

prog.lisp. 

(setq n (parse-integer (first EXT:*ARGS*)))

(format t "~A~%" "'Your command, please?', asked the waiter.")

(format t "~@?~%"
          (if (= n 1) "a piece of cake" "~D pieces of cake")
          n)

After being internationalized, all strings are wrapped in I18N:GETTEXT calls, and I18N:NGETTEXT is used for plurals. Also, I18N:TEXTDOMAINDIR is assigned a value; in our case, for simplicity, the current directory.

prog.lisp. 

(setf (textdomain) "prog")
(setf (textdomaindir "prog") "./")

(setq n (parse-integer (first EXT:*ARGS*)))

(format t "~A~%"
          (gettext "'Your command, please?', asked the waiter."))

(format t "~@?~%"
          (ngettext "a piece of cake" "~D pieces of cake" n)
          n)

For ease of reading, it is customary to define an abbreviation for the I18N:GETTEXT function. An underscore is customary.

prog.lisp. 

(setf (textdomaindir "prog") "./")
(defun _ (msgid) (gettext msgid "prog"))

(setq n (parse-integer (first EXT:*ARGS*)))

(format t "~A~%"
          (_"'Your command, please?', asked the waiter."))

(format t "~@?~%"
          (ngettext "a piece of cake" "~D pieces of cake" n "prog")
          n)

Now the program's maintainer creates a message catalog template through the command

$ xgettext -o prog.pot prog.lisp

The message catalog template looks roughly like this.

prog.pot. 

msgid "'Your command, please?', asked the waiter."
msgstr ""

msgid "a piece of cake"
msgid_plural "%d pieces of cake"
msgstr[0] ""
msgstr[1] ""

Then a French translator creates a French message catalog

prog.fr.po. 

msgid ""
msgstr ""
"Content-Type: text/plain; charset=ISO-8859-1\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"

msgid "'Your command, please?', asked the waiter."
msgstr "«Votre commande, s'il vous plait», dit le garçon."

# Les gateaux allemands sont les meilleurs du monde.
msgid "a piece of cake"
msgid_plural "%d pieces of cake"
msgstr[0] "un morceau de gateau"
msgstr[1] "%d morceaux de gateau"

and sends it to the program's maintainer.

The program's maintainer compiles the catalog as follows:

$ mkdir -p ./fr/LC_MESSAGES
$ msgfmt -o ./fr/LC_MESSAGES/prog.mo prog.fr.po

When a user in a french LOCALE then runs the program

$ clisp prog.lisp 2

she will get the output

    «Votre commande, s'il vous plait», dit le garçon.
    2 morceaux de gateau