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 -@lisp (asdf:oos 'asdf:load-op :cl-l10n) @end lisp +@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 + +@node I18N +@chapter I18N + +@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}. +@lisp +(defvar *my-bundle* (make-instance 'bundle)) +@end lisp + +Then you add resources to your bundle using either @code{add-resource} +or @code{add-resources}. + +@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/~%") + +@end lisp + +Then by using @code{gettext} you can lookup locale specific strings. +@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` +@end lisp + +A useful trick is to define either a macro or reader macro wrapping +gettext for your specific bundle +eg. +@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)) + +@end lisp + +which would change the @code{timey} function to +@lisp +(defun timey () (format t #"showtime" 3310880446)) +;; or +(defun timey () (format t (_ "showtime") 3310880446)) + +@end lisp + +@section API +@anchor {Generic add-resource} +@deffn {Generic} add-resource bundle from to locale-name +Adds an entry to @emph{bundle} for @emph{locale-name} mappings +@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. +@lisp +;; Add mapping for welcome for Afrikaans languages. +(add-resource *my-bundle* "welcome" "welkom" "af_") +@end lisp +@end deffn + +@anchor {Macro add-resources} +@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. +@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_") + +@end lisp +@end deffn + +@anchor {Function gettext} +@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. +@end deffn

@node Notes