https://github.com/gullerya/i18n
client (browser) oriented internationalization library
https://github.com/gullerya/i18n
Last synced: about 2 months ago
JSON representation
client (browser) oriented internationalization library
- Host: GitHub
- URL: https://github.com/gullerya/i18n
- Owner: gullerya
- License: mit
- Created: 2019-11-06T15:18:57.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-11T16:03:09.000Z (almost 4 years ago)
- Last Synced: 2025-03-16T20:37:53.527Z (3 months ago)
- Language: JavaScript
- Size: 450 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
[](https://github.com/gullerya/i18n)
[](https://www.npmjs.com/package/@gullerya/i18n)
[](https://travis-ci.org/gullerya/i18n)
[](https://codecov.io/gh/gullerya/i18n/branch/master)
[](https://www.codacy.com/app/gullerya/i18n)
# Summary
__`i18n`__ is a client (browser) oriented library providing an easy means to quickly internationalize web sites.
As of now the library takes care of __translation__ aspect only. Other kinds of formatting / symboling needs might be considered as per future needs.
`i18n` is capable of handling complex web-component based sites with the same easiness as a simple 'flat' ones.
Main aspects:
* `i18n` library implemented as a classic service from consumer perspective - import it and use the JS APIs and correlated HTML syntax
* `i18n` library is component-design oriented: each component can and should take care of its own needs
> Sharing of resources is super easy, to be sure. But me myself almost always consider it to be a best practice to strive to a self contained, isolated, independent components, even if in this case it means sacrificing some network and memory.
* data binding part is powered by [`data-tier`](https://www.npmjs.com/package/data-tier) engine
* the whole work performed client side, localization data may be provided in inline fashion or fetched as static resources requested from the backend
* JSON resource format supported
* contact me for other formats support
#### Support matrix
61+ | 60+ | 79+
#### Last versions (full changelog is [here](docs/changelog.md))
* __0.1.0__
* Next take - mostly finalized APIs
* __0.0.1__
* Initial implementation
# API
APIs described in this [documentation](docs/api.md).
# Basic usage example
Generally, it is highly advised to read some of the [`data-tier`](https://www.npmjs.com/package/data-tier) documentation. Being an underlying engine, it has everything needed to understand usage and internals of `i18n`.
Import the library as in example below:
```javascript
import * as i18n from './dist/i18n.min.js';
```
Define your language data per component as following:
```javascript
i18n.definePack(packKey, {
en: { ... }, // inlining data
he: '/i18n/about-he.json', // fetched resource
ru: () => { ... } // function returning data
}, options);
```
Parameters description (`sources` stands for the second parameter):
* `packKey` - unique key per component/pack, required
* `sources` - sources of localized texts, required
* `JSON`, keys of which considered to be a locale keys
* properties values may be either
* `options` - reserved, optional
> Under component I mean any level of segregation up to consumers arbitrary choice. One may define such a pack for each and every micro part in UI, other may throw together all of the language data for the whole site.
> Pro tip: it really makes sense to split/pack i18n data according to the components visibility, so that 'About' page texts, for example, won't be dealt with until actually navigated to.
Use the following syntax in your `HTML` resources:
```html
```
Let's break that attribute to the parts to get is clear:
* `i18n` - is the default tying namespace, you can change it via `setNamespace` API; the namespace is __global__ for the whole application
* `packKey` - first token in the path to the localized text is the component / pack key, used when the internatiolization resources was defined
* `path.to.text` - rest of the path is just a path within the localization data graph
# Links
* [API definitions](docs/api.md)
* [Example 1 - end to end working example](docs/examples/example-a/example-a.md)