As any programmer that has ever had to deal with making his or her code readable in more than one locale, the process of sufficiently abstracting program messages from their presentation to the user is non-trivial without help from the programming language. Most modern programming language libraries do provide some mechanism for performing this separation.
A portable API that allows a piece of code to run without modification in different countries and under different languages is a must for any non-trivial software project. The interface should separate the logic of a program from the myriad of translations that may be necessary.
The interface described in this document provides such functionality. The underlying implementation is also allowed to use whatever datastructures it likes to provide access to the translations in the most efficient manner possible. In addition, the implementation is provided with standardized functions that programs will use for accessing an external, unspecified repository of translations.
This interface does not cover all aspects of localization, including support for non-latin characters, number and date formatting, etc. Such functionality is the scope of a future SRFI that may extend this one.
A Message Bundle is a set of message templates and their identifying keys. Each bundle contains one or more such key/value pairs. The bundle itself is associated with a bundle specifier which uniquely identifies the bundle.
A Bundle Specifier is a Scheme list that describes, in order of importance, the package and locale of a message bundle. In most cases, a locale specifier will have between one and three elements. The first element is a symbol denoting the package for which this bundle applies. The second and third elements denote a locale. The second element (first element of the locale) if present, is the two letter, ISO 639-1 language code for the bundle. The third element, if present, is a two letter ISO 3166-1 country code. In some cases, a fourth element may be present, specifying the encoding used for the bundle. All bundle specifier elements are Scheme symbols.
If only one translation is provided, it should be designated only by a package name, for example (mathlib). This translation is called the default translation.
When a message template is retrieved from a bundle, the Scheme implementation will provide the locale under which the system is currently running. When the template is retrieved, the package name will be specified. The Scheme system should construct a Bundle Specifier from the provided package name and the active locale. For example, when retrieving a message template for French Canadian, in the mathlib package, the bundle specifier '(mathlib fr ca)' is used. A program may also retrieve the elements of the current locale using the no-argument procedures:
current-language ->
symbol
current-language symbol ->
undefined
When given no arguments, returns the current ISO 639-1 language code as a symbol. If provided with an argument, the current language is set to that named by the symbol for the currently executing Scheme thread (or for the entire Scheme system if such a distinction is not possible).
current-country ->
symbol
current-country symbol ->
undefined
returns the current ISO 3166-1 country code as a symbol. If provided with an argument, the current country is set to that named by the symbol for the currently executing Scheme thread (or for the entire Scheme system if such a distinction is not possible).
current-locale-details -> list of
symbols
current-locale-details list-of-symbols ->
undefined
Returns a list of additional locale details as a list of symbols. This list may contain information about encodings or other more specific information. If provided with an argument, the current locale details are set to those given in the currently executing Scheme thread (or for the entire Scheme system if such a distinction is not possible).
The Scheme System should first check for a bundle with the exact name provided. If no such bundle is found, the last element from the list is removed and a search is tried for a bundle with that name. If no bundle is then found, the list is shortened by removing the last element again. If no message is found and the bundle specifier is now the empty list, an error should be raised.
The reason for this search order is to provide the most locale sensitive template possible, but to fall back on more general templates if a translation has not yet been provided for the given locale.
A message template is a localized message that may or may not contain one of a number of formatting codes. A message template is a Scheme string. The string is of a form that can be processed by the format procedure found in many Scheme systems and formally specified in SRFI-28 (Basic Format Strings).
This SRFI also extends SRFI-28 to provide an additional format escape code:
~[n]@* - Causes a value-requiring escape code that follows this code immediately to reference the [N]'th optional value absolutely, rather than the next unconsumed value. The referenced value is not consumed.This extension allows optional values to be positionally referenced, so that message templates can be constructed that can produce the proper word ordering for a language.
declare-bundle! bundle-specifier
association-list -> undefined
Declares a new bundle named by the given bundle-specifier. The contents of the bundle are defined by the provided association list. The list contains associations between Scheme symbols and the message templates (Scheme strings) they name. If a bundle already exists with the given name, it is overwritten with the newly declared bundle.store-bundle bundle-specifier -> boolean
Attempts to store a bundle named by the given bundle specifier, and previously made available using declare-bundle! or load-bundle!, in an unspecified mechanism that may be persistent across Scheme system restarts. If successful, a non-false value is returned. If unsuccessful, #f is returned.load-bundle! bundle-specifier -> boolean
Attempts to retrieve a bundle from an unspecified mechanism which stores bundles outside the Scheme system. If the bundle was retrieved successfully, the function returns a non-false value, and the bundle is immediately available to the Scheme system. If the bundle could not be found or loaded successfully, the function returns #f, and the Scheme system's bundle registry remains unaffected.A compliant Scheme system may choose not to provide any external mechanism to store localized bundles. If it does not, it must still provide implementations for store-bundle and load-bundle!. In such a case, both functions must return #f regardless of the arguments given. Users of this SRFI should recognize that the inability to load or store a localized bundle in an external repository is not a fatal error.
localized-template package-name
message-template-name -> string or #f
Retrieves a localized message template for the given package name and the given message template name (both symbols). If no such message could be found, false (#f) is returned.After retrieving a template, the calling program can use format to produce a string that can be displayed to the user.
(let ((translations
'(((en) . ((time . "Its ~a, ~a.")
(goodbye . "Goodbye, ~a.")))
((fr) . ((time . "~1@*~a, c'est ~a.")
(goodbye . "Au revoir, ~a."))))))
(for-each (lambda (translation)
(let ((bundle-name (cons 'hello-program (car translation))))
(if (not (load-bundle! bundle-name))
(begin
(declare-bundle! bundle-name (cdr translation))
(store-bundle! bundle-name)))))
translations))
(define localized-message
(lambda (message-name . args)
(apply format (cons (localized-template 'hello-program
message-name)
args))))
(let ((myname "Fred"))
(display (localized-message 'time "12:00" myname))
(display #\newline)
(display (localized-message 'goodbye myname))
(display #\newline))
;; Displays (English):
;; Its 12:00, Fred.
;; Goodbye, Fred.
;;
;; French:
;; Fred, c'est 12:00.
;; Au revoir, Fred.
The implementation requires that the Scheme system provide a
definition for current-language and
current-country capable of distinguishing the correct
locale present during a Scheme session. The definitions of
those functions in the reference implementation are not capable
of that distinction. Their implementation is provided only so
that the following code can run in any R4RS scheme system.
In addition, the below implementation of a compliant format requires SRFI-6 (Basic String Ports) and SRFI-23 (Error reporting)
;; The association list in which bundles will be stored
(define *localization-bundles* '())
;; The current-language and current-country functions provided
;; here must be rewritten for each Scheme system to default to the
;; actual locale of the session
(define current-language
(let ((current-language-value 'en))
(lambda args
(if (null? args)
current-language-value
(set! current-language-value (car args))))))
(define current-country
(let ((current-country-value 'us))
(lambda args
(if (null? args)
current-country-value
(set! current-country-value (car args))))))
;; The load-bundle! and store-bundle! both return #f in this
;; reference implementation. A compliant implementation need
;; not rewrite these procedures.
(define load-bundle!
(lambda (bundle-specifier)
#f))
(define store-bundle!
(lambda (bundle-specifier)
#f))
;; Declare a bundle of templates with a given bundle specifier
(define declare-bundle!
(letrec ((remove-old-bundle
(lambda (specifier bundle)
(cond ((null? bundle) '())
((equal? (caar bundle) specifier)
(cdr bundle))
(else (cons (car bundle)
(remove-old-bundle specifier
(cdr bundle))))))))
(lambda (bundle-specifier bundle-assoc-list)
(set! *localization-bundles*
(cons (cons bundle-specifier bundle-assoc-list)
(remove-old-bundle bundle-specifier
*localization-bundles*))))))
;;Retrieve a localized template given its package name and a template name
(define localized-template
(letrec ((rdc
(lambda (ls)
(if (null? (cdr ls))
'()
(cons (car ls) (rdc (cdr ls))))))
(find-bundle
(lambda (specifier template-name)
(cond ((assoc specifier *localization-bundles*) =>
(lambda (bundle) bundle))
((null? specifier) #f)
(else (find-bundle (rdc specifier)
template-name))))))
(lambda (package-name template-name)
(let loop ((specifier (cons package-name
(list (current-language)
(current-country)))))
(and (not (null? specifier))
(let ((bundle (find-bundle specifier template-name)))
(and bundle
(cond ((assq template-name bundle) => cdr)
((null? (cdr specifier)) #f)
(else (loop (rdc specifier)))))))))))
;;An SRFI-28 and SRFI-29 compliant version of format. It requires
;;SRFI-23 for error reporting.
(define format
(lambda (format-string . objects)
(let ((buffer (open-output-string)))
(let loop ((format-list (string->list format-string))
(objects objects)
(object-override #f))
(cond ((null? format-list) (get-output-string buffer))
((char=? (car format-list) #\~)
(cond ((null? (cdr format-list))
(error 'format "Incomplete escape sequence"))
((char-numeric? (cadr format-list))
(let posloop ((fl (cddr format-list))
(pos (string->number
(string (cadr format-list)))))
(cond ((null? fl)
(error 'format "Incomplete escape sequence"))
((and (eq? (car fl) '#\@)
(null? (cdr fl)))
(error 'format "Incomplete escape sequence"))
((and (eq? (car fl) '#\@)
(eq? (cadr fl) '#\*))
(loop (cddr fl) objects (list-ref objects pos)))
(else
(posloop (cdr fl)
(+ (* 10 pos)
(string->number
(string (car fl)))))))))
(else
(case (cadr format-list)
((#\a)
(cond (object-override
(begin
(display object-override buffer)
(loop (cddr format-list) objects #f)))
((null? objects)
(error 'format "No value for escape sequence"))
(else
(begin
(display (car objects) buffer)
(loop (cddr format-list)
(cdr objects) #f)))))
((#\s)
(cond (object-override
(begin
(display object-override buffer)
(loop (cddr format-list) objects #f)))
((null? objects)
(error 'format "No value for escape sequence"))
(else
(begin
(write (car objects) buffer)
(loop (cddr format-list)
(cdr objects) #f)))))
((#\%)
(if object-override
(error 'format "Escape sequence following positional override does not require a value"))
(display #\newline buffer)
(loop (cddr format-list) objects #f))
((#\~)
(if object-override
(error 'format "Escape sequence following positional override does not require a value"))
(display #\~ buffer)
(loop (cddr format-list) objects #f))
(else
(error 'format "Unrecognized escape sequence"))))))
(else (display (car format-list) buffer)
(loop (cdr format-list) objects #f)))))))
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Scheme Request For Implementation process or editors, except as needed for the purpose of developing SRFIs in which case the procedures for copyrights defined in the SRFI process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the authors or their successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.