[cl-l10n-cvs] CVS update: cl-l10n/doc/cl-l10n.texi

Wed Dec 1 11:48:48 UTC 2004

Update of /project/cl-l10n/cvsroot/cl-l10n/doc
In directory common-lisp.net:/tmp/cvs-serv28413/doc

Modified Files:
	cl-l10n.texi 
Log Message:
Changelog 2004-12-01
Date: Wed Dec  1 12:48:46 2004
Author: sross

Index: cl-l10n/doc/cl-l10n.texi
diff -u cl-l10n/doc/cl-l10n.texi:1.1.1.1 cl-l10n/doc/cl-l10n.texi:1.2

--- cl-l10n/doc/cl-l10n.texi:1.1.1.1	Mon Nov 29 10:59:09 2004
+++ cl-l10n/doc/cl-l10n.texi	Wed Dec  1 12:48:46 2004
@@ -60,6 +60,7 @@
 * Introduction:         Introduction
 * Getting Started:      Getting Started
 * API:                  API
+* I18N:                 I18N
 * Notes:                Notes
 * Credits:              Credits
 * Index::
@@ -128,9 +129,12 @@
 
 @section Installing
 Once downloaded and symlinked you can load CL-L10N at anytime using
- at lisp (asdf:oos 'asdf:load-op :cl-l10n) @end lisp
+ at code{(asdf:oos 'asdf:load-op :cl-l10n)}
 This will compile CL-L10n the first time it is loaded.
 
+Once installed run @code{(asdf:oos 'asdf:test-op :cl-l10n)} to test
+the package. If any tests fail please send an email to one of the
+mailing lists.
 
 @node API
 @chapter API
@@ -194,8 +198,7 @@
 Example (assuming *locale* is  en_ZA)
 @lisp
 (format t "~:/cl-l10n:format-number/" 1002932)
-1,002,932   ;; Printed
-NIL         ;; Returned
+ prints `1,002,932`
 
 @end lisp
 @end deffn
@@ -215,14 +218,13 @@
 Examples.
 @lisp
 (format t "~/cl-l10n:format-money/" 188232.2322)
-R188,232.23 ;; Printed
-NIL         ;; Returned
+ prints `R188,232.23`
 
 ;; and 
 
 (format t "~:/cl-l10n:format-money/" 188232.2322)
-ZAR 188,232.23   ;; Printed 
-NIL              ;; Returned
+ prints `ZAR 188,232.23`  
+
 @end lisp
 @end deffn
 
@@ -238,8 +240,8 @@
 The format of the time printed is controlled by @code{show-time} and @code{show-date}.
 
 If @emph{fmt} is not nil then @emph{show-date} and @emph{show-time} are ignored 
-and @emph{fmt} is used as the format control string. For details of control
-characters try 'man date'.
+and @emph{fmt} is used as the format control string. For details of format
+directive look at 'man 1 date' although some directives are not supported, namely %U, %V and %W.
 
 Examples (assuming *locale* is ``en_ZA'')
 @lisp
@@ -284,6 +286,114 @@
 Root CL-L10N condition which will be signalled when an exceptional 
 situation occurs.
 @end deftp
+
+ at node I18N
+ at chapter I18N
+
+ at section Internationalisation
+CL-L10N supports internationalised strings through the use 
+of bundles. 
+The process is currently extremely basic, and is bound to 
+change in the future, but is flexible and does what is expected of it.
+
+First you define a bundle using @code{make-instance}.
+ at lisp
+(defvar *my-bundle* (make-instance 'bundle))
+ at end lisp
+
+Then you add resources to your bundle using either @code{add-resource} 
+or @code{add-resources}. 
+
+ at lisp
+(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/~%")
+
+ at end lisp
+
+Then by using @code{gettext} you can lookup locale specific strings.
+ at lisp
+(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`
+ at end lisp
+
+A useful trick is to define either a macro or reader macro wrapping
+gettext for your specific bundle 
+eg.
+ at lisp
+(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))
+
+ at end lisp
+
+which would change the @code{timey} function to 
+ at lisp
+(defun timey () (format t #"showtime" 3310880446))
+;; or 
+(defun timey () (format t (_ "showtime") 3310880446))
+
+ at end lisp
+
+ at section API
+ at anchor {Generic add-resource}
+ at deffn {Generic} add-resource bundle from to locale-name
+Adds an entry to @emph{bundle} for @emph{locale-name}  mappings
+ at emph{from} to @emph{to}. The @emph{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.
+ at lisp
+;; Add mapping for welcome for Afrikaans languages. 
+(add-resource *my-bundle* "welcome" "welkom" "af_")
+ at end lisp
+ at end deffn
+
+ at anchor {Macro add-resources}
+ at deffn {Macro} add-resources (bundle locale-name) &rest entries
+Utility macro to group large amounts of entries into a single
+logical block for a locale.
+ at lisp
+(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_")
+
+ at end lisp
+ at end deffn
+
+ at anchor {Function gettext}
+ at deffn {Function} gettext name bundle &optional (*locale* *locale* )
+Looks for a mapping for @emph{name} in @emph{bundle}. If no mapping
+is found returns name. 
+ at end deffn
 
 
 @node Notes


