Merge branch 'release/1.0.0'

README.md

@@ -4,7 +4,57 @@ A Clojure library designed to provide simple interationalisation of user-facing
 
 ## Usage
 
+To use this library in your project, add the following leiningen dependency:
 
+    [org.clojars.simon_brooke/internationalisation "1.0.0"]
+
+To use it in your namespace, require:
+
+    [scot.weft.i18n.core :refer [get-messages]]
+
+There is only one function you should need to use:
+
+### get-messages
+
+    (get-messages accept-language-header resource-path default-locale)
+
+Return the most acceptable messages collection we have given this accept-language-header. Do not use this function directly, use the memoized variant get-messages, as performance will be very much better.
+
+* `accept-language-header` should be the value of an RFC 2616 Accept-Language header;
+* `resource-path` should be the fully-qualified path name of the directory in which message files are stored;
+* `default-locale` should be a locale specifier to use if no acceptable locale can be identified.
+
+Returns a map of message keys to strings.
+
+See [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt).
+
+## The translation files
+
+Obviously, this only works if you provide files with translations of your interesting strings. These files should contain Clojure maps, and the file names should be the locale string for which the file is relevent followed by the extension ".edn". All the translation files should be in the same directory.
+
+In this project you will find two very simple example files, which should give you the idea:
+
+### en-GB.edn
+
+```
+;;;; This is a British English translation file.
+
+{:pipe "This is not a pipe"}
+```
+
+### fr-FR.edn
+
+```
+;;;; This is a French translation file.
+
+{:pipe "Ceci n'est pas une pipe."}
+```
+
+## Documentation
+
+Documentation may be generated by running
+
+    lein codox
 
 ## License
 

doc/intro.md

@@ -1,3 +1,62 @@
 # Introduction to internationalisation
 
-TODO: write [great documentation](http://jacobian.org/writing/what-to-write/)
+## Usage
+
+To use this library in your project, add the following leiningen dependency:
+
+    [org.clojars.simon_brooke/internationalisation "1.0.0"]
+
+To use it in your namespace, require:
+
+    [scot.weft.i18n.core :refer [get-messages]]
+
+There is only one function you should need to use:
+
+### get-messages
+
+    (get-messages accept-language-header resource-path default-locale)
+
+Return the most acceptable messages collection we have given this accept-language-header. Do not use this function directly, use the memoized variant get-messages, as performance will be very much better.
+
+* `accept-language-header` should be the value of an RFC 2616 Accept-Language header;
+* `resource-path` should be the fully-qualified path name of the directory in which message files are stored;
+* `default-locale` should be a locale specifier to use if no acceptable locale can be identified.
+
+Returns a map of message keys to strings.
+
+See [RFC 2616](https://www.ietf.org/rfc/rfc2616.txt).
+
+## The translation files
+
+Obviously, this only works if you provide files with translations of your interesting strings. These files should contain Clojure maps, and the file names should be the locale string for which the file is relevent followed by the extension ".edn". All the translation files should be in the same directory.
+
+In this project you will find two very simple example files, which should give you the idea:
+
+### en-GB.edn
+
+```
+;;;; This is a British English translation file.
+
+{:pipe "This is not a pipe"}
+```
+
+### fr-FR.edn
+
+```
+;;;; This is a French translation file.
+
+{:pipe "Ceci n'est pas une pipe."}
+```
+
+## Documentation
+
+Documentation may be generated by running
+
+    lein codox
+
+## License
+
+Copyright © 2017 Simon Brooke
+
+Distributed under the Eclipse Public License either version 1.0 or (at
+your option) any later version.

project.clj

@@ -1,7 +1,9 @@
-(defproject org.clojars.simon_brooke/internationalisation "0.1.0-SNAPSHOT"
+(defproject org.clojars.simon_brooke/internationalisation "1.0.0"
   :description "Internationalisation library for Clojure"
   :url "https://github.com/simon-brooke/internationalisation"
   :license {:name "Eclipse Public License"
             :url "http://www.eclipse.org/legal/epl-v10.html"}
   :dependencies [[org.clojure/clojure "1.7.0"]
-                 [instaparse "1.4.7"]])
+                 [com.taoensso/timbre "4.10.0"]
+                 [instaparse "1.4.7"]]
+  :plugins [[lein-codox "0.10.3"]])

resources/i18n/en-GB.edn

@@ -1 +1,3 @@
+;;;; This is a British English translation file.
+
 {:pipe "This is not a pipe"}

resources/i18n/fr-FR.edn

@@ -1 +1,3 @@
+;;;; This is a French translation file.
+
 {:pipe "Ceci n'est pas une pipe."}

src/scot/weft/i18n/core.clj

@@ -3,7 +3,8 @@
   scot.weft.i18n.core
   (:require [clojure.string :as cs]
             [clojure.java.io :as io]
-            [instaparse.core :as insta]))
+            [instaparse.core :as insta]
+            [taoensso.timbre :as timbre]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;;;
@@ -40,6 +41,7 @@
   "From a `parse-tree` generated by the `language-specifier-grammar`, generate
   a list of maps each having a `:language` key, a `:preference` key and a
   `:qualifier` key."
+  {:doc/format :markdown}
   [parse-tree]
   (if
     (nil? parse-tree)
@@ -86,6 +88,7 @@
 
   Returns a list of maps as generated by `generate-accept-languages`, in descending order
   of preference."
+  {:doc/format :markdown}
   [accept-language-header]
   (reverse
     (sort-by
@@ -103,6 +106,7 @@
   message files are stored.
 
   Returns the name of an appropriate file if any is found, else nil."
+  {:doc/format :markdown}
   [language-spec resource-path]
   (cond
     (and
@@ -131,17 +135,20 @@
   identified.
 
   Returns a map of message keys to strings."
+  {:doc/format :markdown}
   [accept-language-header resource-path default-locale]
-  (read-string
+  (let [file-path (first
-    (slurp
+                    (remove
-      (or
+                      nil?
-        (first
+                      (map
-          (remove
+                        #(find-language-file-name % resource-path)
-            nil?
+                        (acceptable-languages accept-language-header))))]
-            (map
+    (timbre/debug (str "Found i18n file at '" file-path "'"))
-              #(find-language-file-name % resource-path)
+    (read-string
-              (acceptable-languages accept-language-header))))
+      (slurp
-        (str resource-path default-locale ".edn")))))
+        (or
+          file-path
+          (str resource-path default-locale ".edn"))))))
 
 
 (def get-messages