From 2d17d0b83b6ec28d9d3f1c7e0c6bb8532408a88c Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Thu, 5 Jan 2023 12:52:20 +0000 Subject: [PATCH] Regenerated documentation - had failed to upversion README! --- README.md | 2 +- doc/intro.md | 37 +++++++++++++++++++++++++++---------- docs/codox/intro.html | 27 ++++++++++++++++++--------- 3 files changed, 46 insertions(+), 20 deletions(-) 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:

 
    
-  
  • *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  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.
    • 
+  
  • :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

-
(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