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 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 SET!able. SET! 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 SET! 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 SET!able. SET! 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.

Function i18n:textdomain-codeset. (i18n:textdomain-codeset DOMAIN) is a place that returns the specified encoding for the strings returned by i18n:gettext and i18n:ngettext. The default value is #f, denoting the default locale encoding. It is SET!able. The value it is set to must be an encoding name known to the system iconv() function. SET! i18n:textdomain-codeset is usually used during the startup phase of a program whose internal string representation is not in the default locale encoding. Note that the TEXTDOMAIN-CODESETs 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 default value is :LC_MESSAGES. Other possible values are :LC_CTYPE, :LC_TIME, :LC_COLLATE, :LC_MONETARY. 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.

(define n (parse-integer (first *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.

(set! (textdomain) "prog")
(set! (textdomaindir "prog") "./")

(define n (parse-integer (first *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.

(set! (textdomaindir "prog") "./")
(define (_ msgid) (gettext msgid "prog"))

(define n (parse-integer (first *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

bash$ xgettext -o prog.pot prog.scm

The message catalog template looks roughly like this.

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

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:

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

When a user in a french locale then runs the program

bash$ guile prog.scm 2

she will get the output

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