# @cherrypulp/i18n

> Simple I18n wrapper around a global object

Latest version **1.4.7** (published 2021-12-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cherrypulp/i18n
pnpm add @cherrypulp/i18n
yarn add @cherrypulp/i18n
bun add @cherrypulp/i18n
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.7 |
| Published | 2021-12-22 |
| First published | 2019-08-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 78.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | dbennani_cherry, danielsum, cherrypulpcom, monkeymonk, anthonypauwels |
| Keywords | i18n, vue, plugin, es6, translations, util, utility |

## Links

- npm: https://www.npmjs.com/package/@cherrypulp/i18n
- Repository: https://gitlab.com/cherrypulp/libraries/js-i18n
- Homepage: https://gitlab.com/cherrypulp/libraries/js-i18n#readme
- Issues: https://gitlab.com/cherrypulp/librariesjs-i18n/issues
- npm.io page: https://npm.io/package/@cherrypulp/i18n

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 1.4.7 (latest) — 2021-12-22
- 1.4.6 — 2021-10-22
- 1.4.5 — 2021-10-22
- 1.4.4 — 2021-10-22
- 1.4.3 — 2021-10-11
- 1.4.2 — 2021-09-22
- 1.4.1 — 2021-09-21
- 1.4.0 — 2021-09-21
- 1.3.4 — 2021-08-06
- 1.3.3 — 2021-08-06
- 1.3.2 — 2021-08-06
- 1.3.1 — 2021-08-06
- 1.3.0 — 2021-08-06
- 1.2.1 — 2021-08-05
- 1.2.0 — 2021-08-05
- … 12 more at https://npm.io/package/@cherrypulp/i18n/versions

## README

# I18n 

[![codebeat badge](https://codebeat.co/badges/fe5b8fc4-34f1-44a6-bcb5-33991d0517bb)](https://codebeat.co/projects/gitlab-com-cherrypulp-libraries-js-i18n-master)
[![Issues](https://img.shields.io/badge/issues-0-brightgreen)](https://gitlab.com/cherrypulp/libraries/js-i18n/issues)
[![License](https://img.shields.io/npm/l/@cherrypulp/i18n)](https://gitlab.com/cherrypulp/libraries/js-i18n/blob/master/LICENSE)
[![npm version](https://badge.fury.io/js/%40cherrypulp%2Fi18n.svg)](https://badge.fury.io/js/%40cherrypulp%2Fi18n)

Simple I18n wrapper around a global object.


## Installation

`npm install @cherrypulp/i18n`


## Quick start

### Initialization

```javascript
import I18n from '@cherrypulp/i18n';

const options = {
    globalName: 'translations', // name of the autoloaded global variable
    forceDisplayKeys: true, // display the key if the label is not found (else it return an empty string)
    storeNotFounds: true, // store every key that are not found in a variable called "_notFounds" inside the global
};

const translations = {
    foo: 'Bar',
    hello: 'Hello :name',
    user: {
        firstname: 'First name',
    },
};
const i18n = new I18n(translations, 'en', options);

// or

window.translations = {
    foo: 'bar',
    hello: 'Hello :Name',
    user: {
        firstname: 'John Doe',
    },
};
const i18n = new I18n();
```

`window.translations` is loaded by default, `translations` will be merged with it.


### Methods

#### `set`

Set translations for the given language (default language is the current one).

```javascript
i18n.set({
	bar: 'BAZ',
}, 'en');
```

#### `add`

Add translations to the given language (default language is the current one).

```javascript
i18n.add({
	foo: 'BAR',
}, 'en');
```


#### `setLocale`

Set current locale.

```javascript
i18n.setLocale('fr'); // i18n.locale return 'fr'
```

#### `has`

Return `true` if the given key exist in translations.

```javascript
i18n.has('foo'); // return true
i18n.has('bat'); // return false
```

#### `get`

> You can now use `__` as an alias of `get`

Return the translation for the given key. You can pass an object as 2nd arguments to replace placeholders in the translation.

```javascript
i18n.get('foo'); // return "bar"
i18n.get('user.firstname'); // return "John Doe"
i18n.get('bat'); // return "bat"
i18n.get('foo', null, 'fr'); // return "foo"
i18n.__('foo', null, 'fr'); // return "foo" (alias)
```

All placeholders are prefixed with a `:`.

```javascript
i18n.get('hello', {name: 'world'}); // return "Hello World"
```

If your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:

```javascript
// @example {hello: 'Hello :NAME'}
i18n.get('hello', {name: 'john'}); // return "Hello JOHN"

// @example {hello: 'Hello :Name'}
i18n.get('hello', {name: 'john'}); // return "Hello John"
```

#### `fetch`

Retrieve a translation from the locale.

```javascript
i18n.fetch('en.foo'); // return "bar"
```

#### `choice`

Singular and plural forms are separated by a `|` (= pipe).

```javascript
// @example {apples: 'There is one apple|There are many apples'}
i18n.choice('apples', 4); // return "There are many apples"
```

You may even create more complex pluralization rules which specify translation strings for multiple number ranges:

```javascript
// @example {apples: '{0} There are none|[1,19] There are some|[20,*] There are many'}
i18n.choice('apples', 4); // return "There are some"
```



### VueJS

```javascript
import { VueI18n } from '@cherrypulp/i18n';

const settings = {
    translations: {
        foo: 'BAR',
    },
    language: 'en',
    options: {
        forceDisplayKeys: false,
    },
};

Vue.use(VueI18n, settings);

// then

this.$i18n.get('foo'); // return "BAR"
Vue.$i18n.get('foo'); // return "BAR"
this.__('foo'); // return "BAR"

// or in templates

<div>{{ $i18n.get('foo') }}</div>
<div>{{ __('foo') }}</div>
```

### Composition

```javascript
import { createApp } from 'vue';
import { createI18n, useI18n, __, choice } from '@cherrypulp/i18n';

const app = createApp();
const options = {
    translations: {
        foo: 'BAR',
    },
    language: 'en',
};

// retrieve a global instance or create one (this instance is a singleton)
const i18n = useI18n(options.translations, options.language);

// create a new instance
const i18nOtherInstance = createI18n(options.translations, options.language);

app.config.globalProperties.__ = __;

// then

i18n.get('foo'); // return "BAR"
i18n.__('foo'); // return "BAR" (alias)
__('foo'); // return "BAR" (shortcut using global instance)

// or in templates

<div>{i18n.get('foo')}</div>
<div>{__('foo')}</div>
```

## Versioning

Versioned using [SemVer](http://semver.org/).

## Contribution

Please raise an issue if you find any. Pull requests are welcome!

## Author

  + **Stéphan Zych** - [monkeymonk](https://gitlab.com/monkey_monk)

## License

This project is licensed under the MIT License - see the [LICENSE](https://gitlab.com/cherrypulp/libraries/js-i18n/blob/master/LICENSE) file for details.

---
_Source: https://npm.io/package/@cherrypulp/i18n · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._