https://github.com/edificeio/sijil.js
A simple and elegant i18n library
https://github.com/edificeio/sijil.js
angular i18n internationalization language translation
Last synced: 2 months ago
JSON representation
A simple and elegant i18n library
- Host: GitHub
- URL: https://github.com/edificeio/sijil.js
- Owner: edificeio
- License: agpl-3.0
- Created: 2016-11-03T19:50:35.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2023-10-10T21:20:54.000Z (over 2 years ago)
- Last Synced: 2025-10-02T01:55:13.860Z (9 months ago)
- Topics: angular, i18n, internationalization, language, translation
- Language: TypeScript
- Size: 955 KB
- Stars: 1
- Watchers: 20
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Sijil
#### *[SI]mple [J]son [I]nternationalization [L]ibrary*
[](https://travis-ci.org/web-education/sijil.js)
## 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 :
```json
{
"en": { "hello": "Hi", "bye": "Bye" },
"fr": { "hello": "Salut !", "bye": "Au revoir" }
}
```
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](https://opendigitaleducation.github.io/sijil.js/docs/) )*
## Installation
### Using npm
`npm install opendigitaleducation/sijil.js --save-dev`
### Or bower
>bower cli
`bower install opendigitaleducation/sijil.js`
>bower.json
```json
"dependencies": {
"sijil": "opendigitaleducation/sijil.js#master"
}
```
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 :
```javascript
System.config({
// ... //
map: {
// ... //
'sijil': 'npm:sijil/dist/bundles/sijil.module.umd.js'
// ... //
}
// ... //
})
```
#### Import the module
```typescript
import { SijilModule } from 'sijil'
@NgModule({
imports: [
/* ... */
SijilModule.forRoot(), // In the root module
// OR
SijilModule.forChild() // For lazily loaded modules
/* ... */
]
})
```
#### Inside a component
- Inject the main service :
```typescript
import { BundlesService } from 'sijil'
/* ... */
constructor(/*...*/, private bundlesService: BundlesService, /*...*/){}
```
- Load a bundle :
```typescript
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
```html
hello
hello
count.key
{{ 'hello' | translate }}
{{ 'hello' | translate:{}:'fr' }}
{{ 'count.key' | translate:{itemNumber: 3} }}
```
#### forRoot
```typescript
static forRoot(require?: Type, parser?: Type, options?: SijilOpts): ModuleWithProviders
```
The forRoot method can be used to override the default services :
```typescript
class DummyRequire implements RequireService {
load(){ return new Promise(res => { res({ 'key': 'value'}) }) }
}
class DummyParser implements Parser {
compile(text){ return text }
}
let dummyOpts = { defaultLanguage: 'en' }
@NgModule({
imports: [
/* ... */
SijilModule.forRoot(DummyRequire, DummyParser, dummyOpts)
/* ... */
]
})
```
### *Without angular2*
Include via a `
```
```javascript
// Loads /docs/language.json file.
Sijil.loadBundle('/docs/' + Sijil.defaultLanguage + '.json').then(function(){
// Adds the 'test' key to the bundle.
Sijil.addToBundle({ 'test': '[OK] Sijil is now loaded.' })
// Logs it.
console.log(Sijil.translate('test'))
})
```
#### factory :
The factory method can be used to override the default services :
```typescript
// Internal definition of the factory function :
Sijil['factory'] = (require: RequireService, parser: Parser, opts: SijilOpts) => {
return new BundlesService(require || new XHRRequire(), parser || new FragmentsParser(), opts || defaultSijilOpts)
}
```
```javascript
// Usage in your code :
let sijilInstance = Sijil.factory({
// Dummy loader
load: () => { return new Promise(res => { res({ 'key': 'value'}) }) },
}, {
// Dummy parser
compile: (text) => text
}, {
// Dummy options
defaultLanguage: 'en'
})
sijilInstance.loadBundle().then(() => { console.log(sijilInstance.translate('key')) })
// <-- 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.
```typescript
loadBundle(where, lang?: string) : Promise
```
#### 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.
```typescript
translate(key: string, parameters?: Object | any[], lang?: string) : string
```
#### unloadBundle
Removes a bundle from the bundles list.
```typescript
unloadBundle(lang: string) : void
```
#### getLoadedLanguages
Returns a list of all loaded languages.
```typescript
getLoadedLanguages() : string[]
```
## Architecture
### Require Service
A RequireService is used to fetch bundles. It contains a single `load: (from: any) => Promise` 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`