Sijil
[SI]mple [J]son [I]nternationalization [L]ibrary
Introduction
Sijil is a simple but powerful i18n library. It can be used in conjunction with angular2, or as an old fashioned <script> inclusion.
Sijil is (very) basically a javascript object with one entry by language loaded, which contains all the translations available as key/values.
Like this :
But the interesting part is that we can use parameters and combine them with the final output.
Here is {{ name ? name : Nobody }} and {{ male ? his : her }} {{ 1 < bunnyCount ? $bunnyCount bunnies : bunny }}.
The library is also completely customizable, from the Loader to the Parser.
( Demo )
Installation
Using npm
npm install opendigitaleducation/sijil.js --save-dev
Or bower
bower cli
bower install opendigitaleducation/sijil.js
bower.json
"dependencies":
Then : bower install
Or build it yourself
- clone this repo
npm install
npm start
Distribution files will be located inside the dist
folder.
Use it
With angular2
Use the es6 files (index.js
as the entry point) and d.ts definitions, or the umd.bundle (dist/bundles/sijil.module.umd.js
).
For example, with SystemJs loader, inside the systemjs.config.js
file :
System
Import the module
Inside a component
- Inject the main service :
/* ... */ constructor/*...*/, private bundlesService: BundlesService, /*...*/
- Load a bundle :
this.bundlesService.loadBundle'/path/to/the/language/file.json', 'en' .then/* The bundle is loaded. */ .catch...
The default loader will perform an http request at the specified path to retrieve a json file. The contents will be added to the current language bundle (or the specified language as the 2nd argument).
- Inside a template
<!-- USING THE S5L HTML TAG --> hello <!-- Force a language --> hello <!-- With parameters --> count.key <!-- count.key being mapped to something like "There {{ itemNumber > 1 ? are $itemNumber items : is one item }} in the room" --> <!-- USING THE TRANSLATE PIPE --> {{ 'hello' | translate }} <!-- As an attribute --> <!-- Force a language --> {{ 'hello' | translate:{}:'fr' }} <!-- With parameters --> {{ 'count.key' | translate:{itemNumber: 3} }}
forRoot
static forRootrequire?: Type<RequireService>, parser?: Type<Parser>, options?: SijilOpts: ModuleWithProviders
The forRoot method can be used to override the default services :
Without angular2
Include via a <script src="[your.sijil.path]/dist/bundles/sijil.js></script>
tag.
Then use the global Sijil
object as needed.
// Loads /docs/language.json file.Sijil
factory :
The factory method can be used to override the default services :
// Internal definition of the factory function :Sijil =
// Usage in your code :let sijilInstance = SijilsijilInstance// <-- Outputs 'value'
Methods
loadBundle
or loadBundles for multiple bundles
Loads a bundle and associates it with a language. If the target language already contains key/values, then we mixin the new bundle and the existing one.
loadBundlewhere, lang?: string : Promise<void>
translate
the method called by the translate pipe and the s5l tag
Translates a single key into a target language, using the parameters provided if needed.
translatekey: string, parameters?: Object | any, lang?: string : string
unloadBundle
Removes a bundle from the bundles list.
unloadBundlelang: string : void
getLoadedLanguages
Returns a list of all loaded languages.
getLoadedLanguages : string
Architecture
Require Service
A RequireService is used to fetch bundles. It contains a single load: (from: any) => Promise<Object>
method,
which loads the bundle according to its argument value.
The default RequireService provided (HttpRequireService for angular2 users, XhrRequireService otherwise) fetches the bundles from an url and parses json from the reponse.
Parser Service
A ParserService computes any logic provided in the translations.
- Input : 'raw' translation + parameters (Object or Array)
- Output : 'compiled' translation
The default provider instanciates a FragmentsParserService, which accepts the syntax described below.
FragmentsParserService
Logic is contained inside mustache blocks : {{ logic block }}
There are two variants :
A single parameter key or index
A key when the parameters are contained inside an object or an index when the parameters are contained inside an array
Examples:
{{ key }}
+ { "key" : "my key" }
= my key
{{ 1 }}
+ [1, 2]
= 2
A ternary-like condition
{{ condition ? trueValue : falseValue }}
{{ leftClause operator rightClause ? trueValue : falseValue }}
Where condition may be either a single parameter key/index, or 2 clauses with the following operators : ==, >, =>, <=, <
Examples:
the $ sign is used in ambiguous cases to refer to the parameter
{{ count > 1 ? $count cats : 1 cat }}
+ {"count": 10}
= 10 cats
{{ 1 < count ? $count cats : 1 cat }}
+ {"count": 1}
= 1 cat
Parameters array or parameter objects ?
The syntax is the same, but with indexes instead of names :
{{ $0 > 1 ? $0 cats : 1 cat }}
+ [10]
= 10 cats
{{ 1 < $0 ? $0 cats : 1 cat named $1 }}
+ [1, 'Albert']
= 1 cat named Albert