Tongue is a do-it-yourself i18n library for Clojure and ClojureScript.
Tongue is very simple yet capable:
- Dictionaries are just Clojure maps.
- Translations are either strings, template strings or arbitrary functions.
- No additional build steps, no runtime resource loading.
- It comes with no built-in knowledge of world locales. It has all the tooling for you to define locales yourself though.
- Pure Clojure implementation, no dependencies.
- Can be used from both Clojure and ClojureScript.
In contrast with other i18n solutions relying on complex and limiting string-based syntax for defining pluralization, wording, special cases etc, Tongue lets you use arbitrary functions. It gives you convenience, code reuse and endless possibilities.
As a result you have a library that handles exactly your case well with as much detail and precision as you need.
Who’s using Tongue?
Setup
Add to project.clj:
[tongue "0.4.4"]In production:
- Add
-Dclojure.spec.compile-asserts=falseto JVM options (actual JVM on Clojure, during build on ClojureScript)
In development:
- Add
-Dclojure.spec.check-asserts=trueto JVM options.
Usage
Define dictionaries:
(require '[tongue.core :as tongue])
(def dicts
{ :en { ;; simple keys
:color "Color"
:flower "Flower"
;; namespaced keys
:weather/rain "Rain"
:weather/clouds "Clouds"
;; nested maps will be unpacked into namespaced keys
;; this is purely for ease of dictionary writing
:animals { :dog "Dog" ;; => :animals/dog
:cat "Cat" } ;; => :animals/cat
;; substitutions
:welcome "Hello, {1}!"
:between "Value must be between {1} and {2}"
;; For using a map
:mail-title "{user}, {title} - Message received."
;; aliases, to share common strings but still use specific i18n keys
:frontpage-greeting :welcome
;; arbitrary functions
:count (fn [x]
(cond
(zero? x) "No items"
(= 1 x) "1 item"
:else "{1} items")) ;; you can return string with substitutions
;; optional -- override “Missing key” message
:tongue/missing-key "Missing key {1}"
}
:en-GB { :color "colour" } ;; sublang overrides
:tongue/fallback :en } ;; fallback locale keyThen build translation function:
(def translate ;; [locale key & args] => string
(tongue/build-translate dicts))And go use it:
(translate :en :color) ;; => "Color"
;; namespaced keys
(translate :en :animals/dog) ;; => "Dog", taken from { :en { :animals { :dog "Dog }}}
;; substitutions
(translate :en :welcome "Nikita") ;; => "Hello, Nikita!"
(translate :en :between 0 100) ;; => "Value must be between 0 and 100"
(translate :en :mail-title {:user "Tom" :title "New message"}) ;; => "Tom, New message - Message received."
;; if key resolves to fn, it will be called with provided arguments
(translate :en :count 0) ;; => "No items"
(translate :en :count 1) ;; => "1 item"
(translate :en :count 2) ;; => "2 items"
;; multi-tag locales will fall back to more generic versions
;; :zh-Hans-CN will look in :zh-Hans-CN first, then :zh-Hans, then :zh, then fallback locale
(translate :en-GB :color) ;; => "Colour", taken from :en-GB
(translate :en-GB :flower) ;; => "Flower", taken from :en
;; if there’s no locale or no key in locale, fallback locale is used
(translate :ru :color) ;; => "Color", taken from :en as a fallback locale
;; if nothing can be found at all
(translate :en :unknown) ;; => "|Missing key :unknown|"Localizing numbers
Tongue can help you build localized number formatters:
(def format-number-en ;; [number] => string
(tongue/number-formatter { :group ","
:decimal "." }))
(format-number-en 9999.9) ;; => "9,999.9"Use it directly or add :tongue/format-number key to locale’s dictionary. That way format will be applied to all numeric substitutions:
(def dicts
{ :en { :tongue/format-number format-number-en
:count "{1} items" }
:ru { :tongue/format-number (tongue/number-formatter { :group " "
:decimal "," })
:count "{1} штук" }})
(def translate
(tongue/build-translate dicts))
;; if locale has :tongue/format-number key, substituted numbers will be formatted
(translate :en :count 9999.9) ;; => "9,999.9 items"
(translate :ru :count 9999.9) ;; => "9 999,9 штук"
;; hint: if you only need a number, use :tongue/format-number key directly
(translate :en :tongue/format-number 9999.9) ;; => "9,999.9"Localizing dates
It works almost the same way as with numbers, but requires a little more setup.
First, you’ll need locale strings:
(def inst-strings-en
{ :weekdays-narrow ["S" "M" "T" "W" "T" "F" "S"]
:weekdays-short ["Sun" "Mon" "Tue" "Wed" "Thu" "Fri" "Sat"]
:weekdays-long ["Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday"]
:months-narrow ["J" "F" "M" "A" "M" "J" "J" "A" "S" "O" "N" "D"]
:months-short ["Jan" "Feb" "Mar" "Apr" "May" "Jun" "Jul" "Aug" "Sep" "Oct" "Nov" "Dec"]
:months-long ["January" "February" "March" "April" "May" "June" "July" "August" "September" "October" "November" "December"]
:dayperiods ["AM" "PM"]
:eras-short ["BC" "AD"]
:eras-long ["Before Christ" "Anno Domini"] })Feel free to omit keys you’re not going to use. E.g. for ISO 8601 none of these strings are used at all.
Then build a datetime formatter:
(def format-inst ;; [inst] | [inst tz] => string
(tongue/inst-formatter "{month-short} {day}, {year} at {hour12}:{minutes-padded} {dayperiod}" inst-strings-en))And it’s ready to use:
(format-inst #inst "2016-07-11T22:31:00+06:00") ;; => "Jul 11, 2016 at 4:31 PM"
(format-inst
#inst "2016-07-11T22:31:00+06:00"
(java.util.TimeZone/getTimeZone "Asia/Novosibirsk")) ;; => "Jul 11, 2016 at 10:31 PM"tongue.core/inst-formatter builds a function that has two arities: just instant or instant and timezone:
| Clojure | ClojureScript | |
|---|---|---|
instant: clojure.core/Inst protocol implementations |
java.util.Date, java.time.Instant, ... |
js/Date, ... |
| timezone | java.util.Timezone |
integer GMT offset in minutes, e.g. 360 for GMT+6 |
| if tz is omitted | assume UTC | assume browser timezone |
As with numbers, put a :tongue/format-inst key into dictionary to get default formatting for datetime substitutions:
(def dicts
{ :en { :tongue/format-inst (tongue/inst-formatter "{month-short} {day}, {year}" inst-strings-en)
:published "Published at {1}" } })
(def translate
(tongue/build-translate dicts))
;; if locale has :tongue/format-inst key, substituted instants will be formatted using it
(translate :en :published #inst "2016-01-01") ;; => "Published at January 1, 2016"Use multiple keys if you need several datetime format options:
(def dicts
{ :en
{ :date-full (tongue/inst-formatter "{month-long} {day}, {year}" inst-strings-en)
:date-short (tongue/inst-formatter "{month-numeric}/{day}/{year-2digit}" inst-strings-en)
:time-military (tongue/inst-formatter "{hour24-padded}{minutes-padded}")}})
(def translate (tongue/build-translate dicts))
(translate :en :date-full #inst "2016-01-01T15:00:00") ;; => "January 1, 2016"
(translate :en :date-short #inst "2016-01-01T15:00:00") ;; => "1/1/16"
(translate :en :time-military #inst "2016-01-01T15:00:00") ;; => "1500"
;; You can use timezones too
(def tz (java.util.TimeZone/getTimeZone "Asia/Novosibirsk")) ;; GMT+6
(translate :en :time-military #inst "2016-01-01T15:00:00" tz) ;; => "2100"Full list of formatting options:
| Code | Example | Meaning |
|---|---|---|
{hour24-padded} |
00, 09, 12, 23 | Hour of day (00-23), 0-padded |
{hour24} |
0, 9, 12, 23 | Hour of day (0-23) |
{hour12-padded} |
12, 09, 12, 11 | Hour of day (01-12), 0-padded |
{hour12} |
12, 9, 12, 11 | Hour of day (1-12) |
{dayperiod} |
AM, PM | AM/PM from :dayperiods |
{minutes-padded} |
00, 30, 59 | Minutes (00-59), 0-padded |
{minutes} |
0, 30, 59 | Minutes (0-59) |
{seconds-padded} |
0, 30, 59 | Seconds (00-60), 0-padded |
{seconds} |
00, 30, 59 | Seconds (0-60) |
{milliseconds} |
000, 123, 999 | Milliseconds (000-999), always 0-padded |
{weekday-long} |
Wednesday | Weekday from :weekdays-long |
{weekday-short} |
Wed, Thu | Weekday from :weekdays-short |
{weekday-narrow} |
W, T | Weekday from :weekdays-narrow |
{weekday-numeric} |
1, 4, 5, 7 | Weekday number (1-7, Sunday = 1) |
{day-padded} |
01, 15, 29 | Day of month (01-31), 0-padded |
{day} |
1, 15, 29 | Day of month (1-31) |
{month-long} |
January | Month from :months-long |
{month-short} |
Jan, Feb | Month from :months-short |
{month-narrow} |
J, F | Month from :months-narrow |
{month-numeric-padded} |
01, 02, 12 | Month number (01-12, January = 01), 0-padded |
{month-numeric} |
1, 2, 12 | Month number (1-12, January = 1) |
{year} |
1999, 2016 | Full year (0-9999) |
{year-2digit} |
99, 16 | Last two digits of a year (00-99) |
{era-long} |
Anno Domini | Era from :eras-long |
{era-short} |
BC, AD | Era from :eras-short |
... |
... | anything not in {} is printed as-is |
Interpolation
Tongue supports both positional and named interpolations on strings:
(require '[tongue.core :as tongue])
(def dicts
{ :en { :welcome "Hello, {1}!"
:mail-title "{user}, {title} - Message received."
}})
(def tr (tongue/build-translate dicts))
(tr :en :welcome "Nikita") ;; => "Hello, Nikita!"
(tr :en :mail-title {:user "Tom" :title "New message"}) ;; => "Tom, New message - Message received."The dictionary can contain other kinds of values. In that case, interpolation
must be defined for the type by implementing the tongue.core/IInterpolate
interface:
(require '[tongue.core :as tongue])
(extend-type clojure.lang.PersistentVector
tongue/IInterpolate
(interpolate-named [v dicts locale interpolations]
(mapv (fn [x]
(if (and (keyword? x)
(= "arg" (namespace x)))
(get interpolations x)
x)) v))
(interpolate-positional [v dicts locale interpolations]
(mapv (fn [x]
(if (and (vector? x)
(= :arg (first x)))
(nth interpolations (second x))
x)) v)))Now you can put vectors in the dictionary and have values interpolated in them:
(require '[tongue.core :as tongue])
(def dicts
{ :en { :welcome [:div {} "Hello, " [:arg 0]]
:mail-title [:arg/user ", Message received."]
}})
(def tr (tongue/build-translate dicts))
(tr :en :welcome "Nikita")
;; => [:div {} "Hello, " "Nikita"]
(tr :en :mail-title {:arg/user "Tom"})
;; => ["Tom" ", Message received."]Changes
0.4.4 March 23, 2022
- Fixed warning on Clojure 1.11 #35 #36 thx @stevejmp
0.4.3 December 9, 2021
- Override “Missing Key” message with
:tongue/missing-key#32
0.4.2 October 11, 2021
- Make format-argument fn public #31 by @duckyuck
0.4.1 October 11, 2021
- Do not modify String.prototype in CLJS version #29 by @cjohansen
0.4.0 October 5, 2021
- Added IInterpolate protocol #11 #28 thx @cjohansen
0.3.0 June 16, 2021
- Values could be aliased to another keys #8 #10 thx @cjohansen
- Fix ratio formatting #15
0.2.10 September 22, 2020
- Make build-dicts public #26 thx @hoxu
0.2.9 November 14, 2019
- Allow qualified keywords in maps (PR #24, thx @just-sultanov)
0.2.8 October 9, 2019
- Allow dash in map keys (PR #23, thx @mchughs)
0.2.7 July 26, 2019
- Substitute placeholders from a map (PR #22, thx @katsuyasu-murata)
0.2.6
- Fix namespaced keys (PR #20, thx @JoelSanchez)
0.2.5
- Enable deep nesting of dicts (PR #18, thx @valerauko)
- Bumped
clojure-future-specto 1.9.0
0.2.4
- Don’t throw on missing argument index (#13)
0.2.3
[clojure-future-spec "1.9.0-beta4"]
0.2.2
- Fixed incorrect substitution if replacement contained
$(PR #7, thx Christian Johansen)
0.2.1
[clojure-future-spec "1.9.0-alpha17"]- Tongue now works in both 1.8 and 1.9+ Clojure environments
0.2.0
- Removed clojure-future-spec, requires Clojure 1.9 or later
0.1.4
- Use unified
{}syntax instead of<...>/%x
0.1.3
- Date/time formatting can accept arbitrary
Instprotocol implementations
0.1.2
- Date/time formatting
- ClojureScript now runs tests too
- clojure.spec 1.9.0-alpha10
- Disabled spec for ClojureScript
0.1.1
- Absense of format rules shouldn’t break
translate - number-format should not use fallback locale
- updated to clojure.spec 1.9.0-alpha9
0.1.0
Initial release
License
Copyright © 2016 Nikita Prokopov
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.