handlebars-i18n 1.7.1 → 1.8.1

package/readme.md

@@ -8,13 +8,14 @@ the web browser. Supports Typescript.
 Handlebars-i18n is listed amongst i18next’s [framework helpers](https://www.i18next.com/overview/supported-frameworks).
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-![Node.js Version](https://img.shields.io/badge/Node.js-14.x-green)
+![Node.js version](https://img.shields.io/badge/node-%3E%3D14-brightgreen)
 [![Build](https://github.com/fwalzel/handlebars-i18n/actions/workflows/node.js.yml/badge.svg)](https://github.com/fwalzel/handlebars-i18n/actions/workflows/node.js.yml/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/Aller-Couleur/handlebars-i18n/badge.svg?branch=master)](https://coveralls.io/github/Aller-Couleur/handlebars-i18n?branch=master)
 [![Code Climate](https://codeclimate.com/github/Aller-Couleur/handlebars-i18n/badges/gpa.svg)](https://codeclimate.com/github/Aller-Couleur/handlebars-i18n)
 [![Known Vulnerabilities](https://snyk.io/test/github/Aller-Couleur/handlebars-i18n/badge.svg)](https://snyk.io/test/github/Aller-Couleur/handlebars-i18n/badge.svg)
 ![npm](https://img.shields.io/npm/dt/handlebars-i18n)
 ![npm](https://img.shields.io/npm/dm/handlebars-i18n)
+![GitHub stars](https://img.shields.io/github/stars/fwalzel/handlebars-i18n?style=social)
 
 ## License
 
@@ -28,28 +29,27 @@ If you use handlebars-i18n in a professional context, you could
 
 ## Install
 
-If you use version npm >= 7:
-
-```bash
-$ npm i handlebars-i18n
-```
-
-For older versions do:
-
-```bash
-$ npm i handlebars-i18n handlebars@4.7.6 i18next@20.2.1 intl@1.2.5
+```sh
+npm i handlebars-i18n
 ```
 
-## Usage
+## Import
 
-Usage within node environment:
+Import as commonJS within node environment:
 
 ```javascript
 const HandlebarsI18n = require("handlebars-i18n");
 HandlebarsI18n.init();
 ```
 
-Usage in web browser:
+With ES6 import syntax:
+
+```typescript
+import * as HandlebarsI18n from "handlebars-i18n";
+HandlebarsI18n.init();
+```
+
+Usage in web browser (old school):
 
 ```javascript
 <script src="handlebars.js"></script>
@@ -61,12 +61,9 @@ Usage in web browser:
 </script>
 ```
 
-With ES6 import syntax:
-
-```typescript
-import * as HandlebarsI18n from "handlebars-i18n";
-
-HandlebarsI18n.init();
+Via jsDelivr CDN:
+```javascript
+<script src="https://cdn.jsdelivr.net/npm/handlebars-i18n@1.8.0/dist/handlebars-i18n.min.js"></script>
 ```
 
 ## Quick example
@@ -147,21 +144,21 @@ Finally use in template:
 
 * returns for "en" &#x2192; **$1,200.99**
 
-## Further examples
+## Detailed examples
 
 :point_right: See the *examples folder* in the repo for more use cases and details.
 
-- Open `examples/browser-example/index.html` in your Web browser to see an implementation with a simple UI
-- Run `$ npm run example:js` in the console to get a very basic node example logged
-- Run `$ npm run example:ts` to compile and log a typescript example
+- Open `examples/browser-example/index.html` in your Web browser to see an implementation with a simple UI.
+- Run `npm run example:js` in the console to get a very basic node example logged.
+- Run `npm run example:ts` to compile and log a typescript example.
 
 ## Additional CLI Helper for Handlebars-i18n available :metal:
 
 Handlebars-i18n has its own command line
 interface [handlebars-i18n-cli](https://www.npmjs.com/package/handlebars-i18n-cli).
 
-```bash
-$ npm i handlebars-i18n-cli --save-dev
+```sh
+npm i handlebars-i18n-cli --save-dev
 ```
 
 Automatically extract translation strings from handlebars templates and generate i18next conform json files from it.
@@ -197,13 +194,9 @@ Template usage:
 The i18next resource:
 
 ```javascript
-"en"
-:
-{
+"en" : {
   translation : {
-    "whatIsWhat"
-  :
-    "{{a}} is {{b}}."
+    "whatIsWhat" : "{{a}} is {{b}}."
   }
 }
 ```
@@ -215,19 +208,12 @@ The i18next resource:
 ```
 
 ```javascript
-"en"
-:
-{
+"en" : {
   translation : {
-    "keyWithCount"
-  :
-    "{{count}} item",
-      "keyWithCount_plural"
-  :
-    "{{count}} items"
+    "keyWithCount" : "{{count}} item", 
+    "keyWithCount_plural" : "{{count}} items"
   }
-}
-, ...
+}, 
 ```
 
 **Override globally selected language**
@@ -311,51 +297,67 @@ in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
 
 ---
 
-### _dateRel :tada: new in 1.7
+### _dateAdd :tada: new in 1.8
 
-Outputs a string with a relative date statement, formatted according to the language specific conventions.
+Adds a time offset in a given unit to a date, returns the modified date.
 
 ```
-{{_dateRel 7 unit="hour"}}
+{{_dateAdd "1996-12-17" 24 unit="hour"}}
 ```
 
-Will output for "en" &#x2192; **in 7 hours**
+Will output for "en" &#x2192; **12/18/1996**
+
+The first argument is a date (see function **_date** for valid date inputs). The second argument is a time amount given 
+as number. The option **unit** specifies the time amount. Possible units
+are `"second"` | `"minute"` | `"hour"` | `"day"` | `"week"` | `"month"` | `"quarter"` |`"year"` (default is `"hour"`).
+Further options as for function **_date** can be applied.
+
+---
+
+### _dateDiff
+
+Outputs the relative time difference between two given dates.
 
 ```
-{{_dateRel -7 unit="hour"}}
+{{_dateDiff "1996-12-17T00:00:00" "1995-12-17T00:00:00" unit="year"}}
 ```
 
-Will output for "en" &#x2192; **7 hours ago**
+Will output for "en" &#x2192; **in 1 year**
 
-A positive number argument leads to a future event statement, a negative refers to a past date. Possible units
-are `"second"` | `"minute"` | `"hour"` | `"day"` | `"week"` | `"month"` | `"quarter"` |`"year"` (default is `"hour"`). 
-For a complete set of options (such as `numberingSystem` or `localeMatcher`)
-see [Intl.RelativeTimeFormat Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
-Alternatively check this repo’s TS types
-in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
+The second date argument is subtracted from the first. If the difference is a positive value, a future event statement
+is made. A negative value refers to a past date. (If no second argument is given, the default date is the present moment). 
+Allowed date input formats are similar to **_date**, options equal **_dateRel**. Default unit is `"hour"`.
 
 ---
 
-### _dateDiff :tada: new in 1.7
+### _dateRel 
 
-Outputs the time difference between two given dates.
+Outputs a string with a relative date statement, formatted according to the language specific conventions.
 
 ```
-{{_dateDiff "1996-12-17T00:00:00", "1995-12-17T00:00:00" unit="year"}}
+{{_dateRel 7 unit="hour"}}
 ```
 
-Will output for "en" &#x2192; **in 1 year**
+Will output for "en" &#x2192; **in 7 hours**
 
-The second date argument is subtracted from the first. If the difference is a positive value, a future event statement
-is made. A negative value refers to a past date. Allowed date input formats are similar to *_date*, options equal
-**_dateRel**.
+```
+{{_dateRel -7 unit="hour"}}
+```
+
+Will output for "en" &#x2192; **7 hours ago**
+
+A positive number argument leads to a future event statement, a negative refers to a past date. Possible units
+are `"second"` | `"minute"` | `"hour"` | `"day"` | `"week"` | `"month"` | `"quarter"` |`"year"` (default is `"hour"`). 
+For a complete set of options (such as `numberingSystem` or `localeMatcher`)
+see [Intl.RelativeTimeFormat Constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
+Alternatively check this repo’s TS types in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
 
 ---
 
 ### _num
 
-Outputs a formatted number according to the language specific conventions of number representation, e.g. *
-*4,100,000.8314** for "**en**", but **4.100.000,8314** for "**de**".
+Outputs a formatted number according to the language specific conventions of number representation, e.g. 
+**4,100,000.8314** for "**en**", but **4.100.000,8314** for "**de**".
 
 ```
 {{_num 4100000.8314 }}
@@ -378,8 +380,8 @@ Will output **3.14** for "**en**", but **3,14** for "**de**".
 
 ### _price
 
-Outputs a formatted currency string according to the language specific conventions of price representation, e.g. *
-*€9,999.99** for "**en**", but **9.999,99 €** for "**de**".
+Outputs a formatted currency string according to the language specific conventions of price representation, e.g. 
+**€9,999.99** for "**en**", but **9.999,99 €** for "**de**".
 
 ```
 {{_price 9999.99}}
@@ -451,6 +453,8 @@ Call a subset in template with the parameter format="custom-name", like:
 {{_date myDate format="year-only"}}
 ```
 
+Subsets must be defined per language, a subset for "all" is invalid.
+
 ### The lookup cascade
 
 The general lookup cascade is:
@@ -515,8 +519,8 @@ HandlebarsI18n.init(null, i18nextCustom);
 
 ## Run tests
 
-```bash
-$ npm test
+```sh
+npm test
 ```
 
 ## Merci à vous