4. I18N

4.1 Internationalisation

First you define a bundle using make-instance.

(defvar *my-bundle* (make-instance 'bundle))

Then you add resources to your bundle using either add-resource or add-resources.

@verbatim (add-resources (bundle "af_") "showtime" "Dankie, die tyd is ~:@/cl-l10n:format-time/~%")

;; an empty string as the locale matcher becomes the default (add-resources (bundle "") "showtime" "Thanks, the time is ~:@/cl-l10n:format-time/~%")

Then by using gettext you can lookup locale specific strings.

(defun timey () (format t (gettext "showtime" bundle) 3310880446))
(timey) ;; with locale en_ZA
 prints `Thanks, the time is Wed 01 Dec 2004 11:00:46 +0200`

(let ((*locale* (locale "af_ZA")))
  (timey))
 prints `Dankie, di tyd is Wo 01 Des 2004 11:00:46 +0200`

A useful trick is to define either a macro or reader macro wrapping gettext for your specific bundle eg.

(set-dispatch-macro-character
 #\# #\"
 #'(lambda (s c1 c2)
     (declare (ignore c2))
     (unread-char c1 s)
     `(cl-l10n:gettext ,(read s) bundle)))
 
;; or this

(defmacro _ (text)
  `(cl-l10n:gettext ,text bundle))

which would change the timey function to

(defun timey () (format t #"showtime" 3310880446))
;; or 
(defun timey () (format t (_ "showtime") 3310880446))

4.2 API

Generic: add-resource bundle from to locale-name

Adds an entry to bundle for locale-name mapping from to to. The locale-name does not have to be a full name like "en_US" but can be a partial match like "en_". Adding mappings for these two locale-names will result in the mapping for "en_US" being used when the locale is "en_US" and the mapping for "en_" being used when using any other english locale. Adding a mapping for an empty locale-name will become the default.

;; Add mapping for welcome for Afrikaans languages. (add-resource *my-bundle* "welcome" "welkom" "af_")

Macro: add-resources (bundle locale-name) &rest entries

Utility macro to group large amounts of entries into a single logical block for a locale.

(add-resources (bundle "af_") "hello" "hallo" "goodbye" "totsiens" "yes" "ja" "no "nee") == (add-resource bundle "hello" "hallo" "af_") (add-resource bundle "goodbye" "totsiens" "af_") (add-resource bundle "yes" "ja" "af_") (add-resource bundle "no" "nee" "af_")

Function: gettext name bundle &optional (*locale* *locale* )

Looks for a mapping for name in bundle. If no mapping is found returns name.