diff --git a/README.md b/README.md index 8f36ea2..3e18d80 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A Clojure library designed to provide simple interationalisation of user-facing To use this library in your project, add the following leiningen dependency: - [org.clojars.simon_brooke/internationalisation "1.0.4"] + [org.clojars.simon_brooke/internationalisation "1.0.5"] To use it in your namespace, require: diff --git a/doc/intro.md b/doc/intro.md index 309c761..3e18d80 100644 --- a/doc/intro.md +++ b/doc/intro.md @@ -6,7 +6,7 @@ A Clojure library designed to provide simple interationalisation of user-facing To use this library in your project, add the following leiningen dependency: - [org.clojars.simon_brooke/internationalisation "1.0.4"] + [org.clojars.simon_brooke/internationalisation "1.0.5"] To use it in your namespace, require: @@ -62,21 +62,21 @@ For example: (get-message :pipe "de-DE" "i18n" "ru") ``` -So how does this work? When one calls `(get-message token accept-language-header)`, how does it know where to find resources? The answer is that there are two dynamic variables: +So how does this work? When one calls +`(get-message token accept-language-header)`, how does it know where to find resources? The answer is that there is a `*config*` map, with (currently) two significant keys: -* `*resource-path*`, the default path within the resources space on which - translation files will be sought. Initialised to `i18n`. -* `*default-language*`, the language tag for the language to use when no +* `:resource-path`, whose value should be a string representation of the default + path within the resources space on which translation files will be sought. Initialised to `i18n`. +* `:default-language`, the language tag for the language to use when no otherwise suitable language can be identified. Initialised to the default language of the runtime session, so this may well be different on your machine from someone elses running identical software. Thus ```clojure -(binding [*resource-path* "language-files" - *default-language* "en-CA"] - (get-message :pipe "en-GB;q=0.9, fr-FR") -) +(binding [*config* {:resource-path "language-files" + :default-language "en-CA"}] + (get-message :pipe "en-GB;q=0.9, fr-FR")) ``` and ```clojure @@ -116,10 +116,27 @@ In this project you will find two very simple example files, which should give y ## Documentation -Documentation may be generated by running +Documentation can be found here. It may be generated by running lein codox +## Future direction + +It's likely that in future configuration will be extended + +1. To read per-language keys/messages from CSV files; +2. To read per-language keys/messages from database tables; +3. potentially, to read per-language keys/messages from other sources. + +Pull requests implementing any of these things will be welcomed. + +## Deprecated features + +There are still two dynamic configuration variables, `*default-language*` +and `*resource-path*`, but these are now superceded by the `*config*` map, +which is extensible. Consequently, if you are using these configuration +variables in production, you should bind `*config*` to `nil`. + ## License Copyright © 2017 Simon Brooke diff --git a/docs/codox/intro.html b/docs/codox/intro.html index 2213989..8fa9f1c 100644 --- a/docs/codox/intro.html +++ b/docs/codox/intro.html @@ -4,7 +4,7 @@

A Clojure library designed to provide simple interationalisation of user-facing messages.

Usage

To use this library in your project, add the following leiningen dependency:

-
[org.clojars.simon_brooke/internationalisation "1.0.4"]
+
[org.clojars.simon_brooke/internationalisation "1.0.5"]
 

 
To use it in your namespace, require:

 
[scot.weft.i18n.core :refer [get-message get-messages]]
@@ -45,16 +45,15 @@
 
 (get-message :pipe "de-DE" "i18n" "ru")
 

-
So how does this work? When one calls (get-message token accept-language-header), how does it know where to find resources? The answer is that there are two dynamic variables:

+
So how does this work? When one calls (get-message token accept-language-header), how does it know where to find resources? The answer is that there is a *config* map, with (currently) two significant keys:

 
 
Thus

-
(binding [*resource-path* "language-files"
-          *default-language* "en-CA"]
-    (get-message :pipe "en-GB;q=0.9, fr-FR")
-)
+
(binding [*config* {:resource-path "language-files"
+                    :default-language "en-CA"}]
+    (get-message :pipe "en-GB;q=0.9, fr-FR"))
 

 
and

 
(get-message :pipe "en-GB;q=0.9, fr-FR" "language-files" "en-CA")
@@ -79,9 +78,19 @@
 {:pipe "Ceci n'est pas une pipe."}
 

 
Documentation

-
Documentation may be generated by running

+
Documentation can be found here. It may be generated by running

 
lein codox
 

+
Future direction

+
It’s likely that in future configuration will be extended

+
    
+  
  1. To read per-language keys/messages from CSV files;
    2. 
+  
  2. To read per-language keys/messages from database tables;
    3. 
+  
  3. potentially, to read per-language keys/messages from other sources.
    4. 
+

+
Pull requests implementing any of these things will be welcomed.

+
Deprecated features

+
There are still two dynamic configuration variables, *default-language* and *resource-path*, but these are now superceded by the *config* map, which is extensible. Consequently, if you are using these configuration variables in production, you should bind *config* to nil.

 
License

 
Copyright © 2017 Simon Brooke

 
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

\ No newline at end of file