handlebars-i18n 1.8.3 → 1.10.0

package/dist/handlebars-i18n.js

@@ -2,12 +2,11 @@
  * handlebars-i18n.js
  *
  * @author: Florian Walzel
- * @date: 2024-08
  *
  * handlebars-i18n adds features for localization/
  * internationalization to handlebars.js
  *
- * Copyright (c) 2020-24 Florian Walzel, MIT License
+ * Copyright (c) 2020-25 Florian Walzel, MIT License
  *
  *********************************************************************/
 
@@ -381,12 +380,34 @@
          * use like: {{__ "key_name"}}
          * or with attributes: {{__ "key_with_count" count=7}}
          *
-         * @param str
-         * @param attributes
+         * @param key
+         * @param options
          * @returns {*}
          */
-        function (str, attributes) {
-          return new handlebars.SafeString((typeof (i18next) !== 'undefined' ? i18next.t(str, attributes.hash) : str));
+        function (key, options) {
+          const hash = options.hash || {};
+
+          // Force object/array return if needed
+          const result = (typeof i18next !== "undefined")
+            ? i18next.t(key, {...hash, returnObjects: true})
+            : key;
+
+          if (typeof result === "string") {
+            return new handlebars.SafeString(result);
+          }
+          return result;
+        }
+      );
+      handlebars.registerHelper('keyExists',
+        /**
+         * checks if a translation key exists
+         * use like: {{#if (keyExists "myKey")}} {{__ "myKey"}} {{/if}}
+         *
+         * @param {string} key - The translation key to check
+         * @returns {boolean}
+         */
+        function (key) {
+          return i18next.exists(key);
         }
       );
       handlebars.registerHelper('_locale',
@@ -502,7 +523,7 @@
               break;
             default:
               throw new Error('@ handlebars-i18n: invalid argument "unit" was given for _dateAdd.' +
-                'Unit must be either "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year".');
+                'Unit must be one of "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year".');
           }
 
           const dateFormat = new Intl.DateTimeFormat(i18next.language, opts);
@@ -534,6 +555,7 @@
       );
       handlebars.registerHelper('_dateDiff',
         /**
+         * Outputs the relative time difference between two given dates in the requested unit.
          *
          * @param dateInputA
          * @param dateInputB
@@ -629,4 +651,4 @@
       }
     },
   }
-});
+});

package/dist/handlebars-i18n.min.js

@@ -1 +1 @@
-!function(e,t){if("object"==typeof exports&&"object"==typeof module){const e=require("handlebars"),r=require("i18next"),n=require("intl"),a=require("relative-time-format");module.exports=t(e,r,n,a,"TEST"===process?.env?.NODE_ENV)}else if("function"==typeof define&&define.amd)define(["Handlebars","i18next","Intl"],t);else{if("object"!=typeof e.Handlebars||"object"!=typeof e.i18next||"object"!=typeof e.Intl)return console.error("@ handlebars-i18n: One or more dependencies are missing. Check for Handlebars, i18next and Intl."),!1;e.HandlebarsI18n=t(e.Handlebars,e.i18next,e.Intl)}}(this,(function(e,t,r,n,a){"use strict";const o={DateTimeFormat:{standard:{},custom:{}},RelativeTimeFormat:{standard:{all:{unit:"hours"}},custom:{}},NumberFormat:{standard:{},custom:{}},PriceFormat:{standard:{all:{style:"currency",currency:"EUR"}},custom:{}}};let i=JSON.parse(JSON.stringify(o));const s={};function u(e,t){let r=[null].concat(t);return new(e.bind.apply(e,r))}function l(e,t,r){if("object"==typeof e&&"object"==typeof e.hash&&Object.keys(e.hash).length>0){let n=e.hash;if(void 0===n.format)return n;if(void 0!==r.custom[n.format]&&void 0!==r.custom[n.format][t])return r.custom[n.format][t]}return void 0!==r.standard[t]?r.standard[t]:void 0!==r.standard.all?r.standard.all:{}}function c(e,t,r,n){return"string"!=typeof e?(console.error("@ handlebars-i18n.configure(): Invalid argument <"+e+'> First argument must be a string with language code such as "en".'),!1):["DateTimeFormat","RelativeTimeFormat","NumberFormat","PriceFormat"].includes(t)?"object"!=typeof r?(console.error("@ handlebars-i18n.configure(): Invalid argument <"+r+"> Third argument must be an object containing the configuration parameters."),!1):(null==n||"string"==typeof n)&&""!==n&&" "!==n||(console.error("@ handlebars-i18n.configure(): Invalid argument <"+n+"> Fourth argument (optional) must be a string naming your custom format configuration."),!1):(console.error("@ handlebars-i18n.configure(): Invalid argument <"+t+'>. Second argument must be a string with the options key. Use either "DateTimeFormat", "RelativeTimeFormat", "NumberFormat", or "PriceFormat".'),!1)}function m(e,t,r,n){return null!=n?(void 0===i[t].custom[n]&&(i[t].custom[n]={}),i[t].custom[n][e]=r):i[t].standard[e]=r,!0}function g(e){return"number"==typeof e||"string"==typeof e&&""!==e}function d(e){let t;if("number"==typeof e)t=new Date(e);else if("string"==typeof e)if("["===e.charAt(0)&&"]"===e.slice(-1)){let r=(e=e.substring(1,e.length-1).replace(/ /g,"")).split(",");t=u.bind(null,Date)(r)}else t="now"===e.toLowerCase()||"today"===e.toLowerCase()?new Date:new Date(e);else t=new Date;return t}function f(e,t){if("function"==typeof r.RelativeTimeFormat)return new r.RelativeTimeFormat(e,t);if(void 0===s[e])try{s[e]=require(`relative-time-format/locale/${e}`)}catch(e){console.error(e)}return n.addLocale(s[e]),new n(e,t)}function b(e,t){return t=t||"hour",Math.trunc(e/{second:1e3,seconds:1e3,minute:6e4,minutes:6e4,hour:36e5,hours:36e5,day:864e5,days:864e5,week:6048e5,weeks:6048e5,month:2629746e3,months:2629746e3,quarter:78894e5,quarters:78894e5,year:315576e5,years:315576e5}[t])}return{configure:function(e,t,r,n){if("string"!=typeof e&&!Array.isArray(e))return console.error("@ handlebars-i18n.configure(): Invalid argument <"+e+'> First argument must be a string with language code such as "en" or an array with language parameters.'),!1;if(Array.isArray(e)){if(e.length<1)return console.log("@ handlebars-i18n.configure(): You passed an empty array, no parameters taken."),!1;e.forEach((e=>{if(!c(e[0],e[1],e[2],e[3]))return!1;m(e[0],e[1],e[2],e[3])}))}else{if(!c(e,t,r,n))return!1;m(e,t,r,n)}return!0},reset:function(){return i=JSON.parse(JSON.stringify(o)),!0},init:function(n,a){return"object"==typeof n&&null!==n?e=n:null!=n&&console.error("@ handlebars-i18n.init(): Invalid Argument [1] given for overrideHndlbrs. Argument must be the Handlebars object. Using generic Handlebars object instead."),"object"==typeof a&&null!==a?t=a:null!=a&&console.error("@ handlebars-i18n.init(): Invalid Argument [2] given for overrideI18n. Argument must be the i18next object. Using generic i18next object on module level instead."),e.registerHelper("__",(function(r,n){return new e.SafeString(void 0!==t?t.t(r,n.hash):r)})),e.registerHelper("_locale",(function(){return t.language})),e.registerHelper("localeIs",(function(e){return t.language===e})),e.registerHelper("_date",(function(e,n){const a=d(e),o=l(n,t.language,i.DateTimeFormat);return new r.DateTimeFormat(t.language,o).format(a)})),e.registerHelper("_dateAdd",(function(e,n,a){if("number"!=typeof e&&"string"!=typeof e)throw new Error('@ handlebars-i18n: invalid first argument "dateInput" was given for _dateAdd.');if("number"!=typeof n)throw new Error('@ handlebars-i18n: invalid second argument "offset" was given for _dateAdd.');const o=d(e),s=l(a,t.language,i.DateTimeFormat);switch(s.unit=s.unit||"hour",s.unit){case"second":case"seconds":o.setSeconds(o.getSeconds()+n);break;case"minute":case"minutes":o.setMinutes(o.getMinutes()+n);break;case"hour":case"hours":o.setHours(o.getHours()+n);break;case"day":case"days":o.setDate(o.getDate()+n);break;case"week":case"weeks":o.setDate(o.getDate()+7*n);break;case"month":case"months":o.setMonth(o.getMonth()+n);break;case"quarter":case"quarters":o.setMonth(o.getMonth()+3*n);break;case"year":case"years":o.setFullYear(o.getFullYear()+n);break;default:throw new Error('@ handlebars-i18n: invalid argument "unit" was given for _dateAdd.Unit must be either "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year".')}return new r.DateTimeFormat(t.language,s).format(o)})),e.registerHelper("_dateRel",(function(e,r){const n=parseInt(e),a=l(r,t.language,i.RelativeTimeFormat);return f(t.language,a).format(n,a.unit)})),e.registerHelper("_dateDiff",(function(e,r,n){let a,o=l(n,t.language,i.RelativeTimeFormat);if(!g(e))return console.error("@ handlebars-i18n: invalid first argument dateInputA was given for _dateDiff."),null;r=r||"now",a=d(e)-d(r);const s=b(a,o.unit);return f(t.language,o).format(s,o.unit)})),e.registerHelper("_num",(function(e,n){let a=l(n,t.language,i.NumberFormat);return new r.NumberFormat(t.language,a).format(e)})),e.registerHelper("_price",(function(e,n){let a=l(n,t.language,i.PriceFormat);"string"!=typeof a.style&&"string"==typeof a.currency&&(a.style="currency");return new r.NumberFormat(t.language,a).format(e)})),e},...a&&{private:{applyToConstructor:u,configLookup:l,validateArgs:c,setArgs:m,isNumOrString:g,createDateObj:d,getRelDateFormatPolyfill:f,getDateDiff:b}}}}));
+!function(e,t){if("object"==typeof exports&&"object"==typeof module){const e=require("handlebars"),r=require("i18next"),n=require("intl"),a=require("relative-time-format");module.exports=t(e,r,n,a,"TEST"===process?.env?.NODE_ENV)}else if("function"==typeof define&&define.amd)define(["Handlebars","i18next","Intl"],t);else{if("object"!=typeof e.Handlebars||"object"!=typeof e.i18next||"object"!=typeof e.Intl)return console.error("@ handlebars-i18n: One or more dependencies are missing. Check for Handlebars, i18next and Intl."),!1;e.HandlebarsI18n=t(e.Handlebars,e.i18next,e.Intl)}}(this,(function(e,t,r,n,a){"use strict";const o={DateTimeFormat:{standard:{},custom:{}},RelativeTimeFormat:{standard:{all:{unit:"hours"}},custom:{}},NumberFormat:{standard:{},custom:{}},PriceFormat:{standard:{all:{style:"currency",currency:"EUR"}},custom:{}}};let i=JSON.parse(JSON.stringify(o));const s={};function u(e,t){let r=[null].concat(t);return new(e.bind.apply(e,r))}function l(e,t,r){if("object"==typeof e&&"object"==typeof e.hash&&Object.keys(e.hash).length>0){let n=e.hash;if(void 0===n.format)return n;if(void 0!==r.custom[n.format]&&void 0!==r.custom[n.format][t])return r.custom[n.format][t]}return void 0!==r.standard[t]?r.standard[t]:void 0!==r.standard.all?r.standard.all:{}}function c(e,t,r,n){return"string"!=typeof e?(console.error("@ handlebars-i18n.configure(): Invalid argument <"+e+'> First argument must be a string with language code such as "en".'),!1):["DateTimeFormat","RelativeTimeFormat","NumberFormat","PriceFormat"].includes(t)?"object"!=typeof r?(console.error("@ handlebars-i18n.configure(): Invalid argument <"+r+"> Third argument must be an object containing the configuration parameters."),!1):(null==n||"string"==typeof n)&&""!==n&&" "!==n||(console.error("@ handlebars-i18n.configure(): Invalid argument <"+n+"> Fourth argument (optional) must be a string naming your custom format configuration."),!1):(console.error("@ handlebars-i18n.configure(): Invalid argument <"+t+'>. Second argument must be a string with the options key. Use either "DateTimeFormat", "RelativeTimeFormat", "NumberFormat", or "PriceFormat".'),!1)}function m(e,t,r,n){return null!=n?(void 0===i[t].custom[n]&&(i[t].custom[n]={}),i[t].custom[n][e]=r):i[t].standard[e]=r,!0}function g(e){return"number"==typeof e||"string"==typeof e&&""!==e}function f(e){let t;if("number"==typeof e)t=new Date(e);else if("string"==typeof e)if("["===e.charAt(0)&&"]"===e.slice(-1)){let r=(e=e.substring(1,e.length-1).replace(/ /g,"")).split(",");t=u.bind(null,Date)(r)}else t="now"===e.toLowerCase()||"today"===e.toLowerCase()?new Date:new Date(e);else t=new Date;return t}function d(e,t){if("function"==typeof r.RelativeTimeFormat)return new r.RelativeTimeFormat(e,t);if(void 0===s[e])try{s[e]=require(`relative-time-format/locale/${e}`)}catch(e){console.error(e)}return n.addLocale(s[e]),new n(e,t)}function b(e,t){return t=t||"hour",Math.trunc(e/{second:1e3,seconds:1e3,minute:6e4,minutes:6e4,hour:36e5,hours:36e5,day:864e5,days:864e5,week:6048e5,weeks:6048e5,month:2629746e3,months:2629746e3,quarter:78894e5,quarters:78894e5,year:315576e5,years:315576e5}[t])}return{configure:function(e,t,r,n){if("string"!=typeof e&&!Array.isArray(e))return console.error("@ handlebars-i18n.configure(): Invalid argument <"+e+'> First argument must be a string with language code such as "en" or an array with language parameters.'),!1;if(Array.isArray(e)){if(e.length<1)return console.log("@ handlebars-i18n.configure(): You passed an empty array, no parameters taken."),!1;e.forEach((e=>{if(!c(e[0],e[1],e[2],e[3]))return!1;m(e[0],e[1],e[2],e[3])}))}else{if(!c(e,t,r,n))return!1;m(e,t,r,n)}return!0},reset:function(){return i=JSON.parse(JSON.stringify(o)),!0},init:function(n,a){return"object"==typeof n&&null!==n?e=n:null!=n&&console.error("@ handlebars-i18n.init(): Invalid Argument [1] given for overrideHndlbrs. Argument must be the Handlebars object. Using generic Handlebars object instead."),"object"==typeof a&&null!==a?t=a:null!=a&&console.error("@ handlebars-i18n.init(): Invalid Argument [2] given for overrideI18n. Argument must be the i18next object. Using generic i18next object on module level instead."),e.registerHelper("__",(function(r,n){const a=n.hash||{},o=void 0!==t?t.t(r,{...a,returnObjects:!0}):r;return"string"==typeof o?new e.SafeString(o):o})),e.registerHelper("keyExists",(function(e){return t.exists(e)})),e.registerHelper("_locale",(function(){return t.language})),e.registerHelper("localeIs",(function(e){return t.language===e})),e.registerHelper("_date",(function(e,n){const a=f(e),o=l(n,t.language,i.DateTimeFormat);return new r.DateTimeFormat(t.language,o).format(a)})),e.registerHelper("_dateAdd",(function(e,n,a){if("number"!=typeof e&&"string"!=typeof e)throw new Error('@ handlebars-i18n: invalid first argument "dateInput" was given for _dateAdd.');if("number"!=typeof n)throw new Error('@ handlebars-i18n: invalid second argument "offset" was given for _dateAdd.');const o=f(e),s=l(a,t.language,i.DateTimeFormat);switch(s.unit=s.unit||"hour",s.unit){case"second":case"seconds":o.setSeconds(o.getSeconds()+n);break;case"minute":case"minutes":o.setMinutes(o.getMinutes()+n);break;case"hour":case"hours":o.setHours(o.getHours()+n);break;case"day":case"days":o.setDate(o.getDate()+n);break;case"week":case"weeks":o.setDate(o.getDate()+7*n);break;case"month":case"months":o.setMonth(o.getMonth()+n);break;case"quarter":case"quarters":o.setMonth(o.getMonth()+3*n);break;case"year":case"years":o.setFullYear(o.getFullYear()+n);break;default:throw new Error('@ handlebars-i18n: invalid argument "unit" was given for _dateAdd.Unit must be one of "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year".')}return new r.DateTimeFormat(t.language,s).format(o)})),e.registerHelper("_dateRel",(function(e,r){const n=parseInt(e),a=l(r,t.language,i.RelativeTimeFormat);return d(t.language,a).format(n,a.unit)})),e.registerHelper("_dateDiff",(function(e,r,n){let a,o=l(n,t.language,i.RelativeTimeFormat);if(!g(e))return console.error("@ handlebars-i18n: invalid first argument dateInputA was given for _dateDiff."),null;r=r||"now",a=f(e)-f(r);const s=b(a,o.unit);return d(t.language,o).format(s,o.unit)})),e.registerHelper("_num",(function(e,n){let a=l(n,t.language,i.NumberFormat);return new r.NumberFormat(t.language,a).format(e)})),e.registerHelper("_price",(function(e,n){let a=l(n,t.language,i.PriceFormat);"string"!=typeof a.style&&"string"==typeof a.currency&&(a.style="currency");return new r.NumberFormat(t.language,a).format(e)})),e},...a&&{private:{applyToConstructor:u,configLookup:l,validateArgs:c,setArgs:m,isNumOrString:g,createDateObj:f,getRelDateFormatPolyfill:d,getDateDiff:b}}}}));

package/examples/browser-example/index.html

@@ -53,7 +53,12 @@
                             'key2': '{{what}} is good.',
                             'key3WithCount': '{{count}} item',
                             'key3WithCount_plural': '{{count}} items',
-                            'key4': 'Selected Language is:'
+                            'key4': 'Selected Language is:',
+                            'fruits': ['Apple', 'Banana', 'Cherry'],
+                            'steps': [
+                                { 'title': 'Step 1', 'text': 'Open the app' },
+                                { 'title': 'Step 2', text: 'Click start' }
+                            ]
                         }
                     },
                     'de' : {
@@ -63,12 +68,18 @@
                             'key2': '{{what}} ist gut.',
                             'key3WithCount': '{{count}} Gegenstand',
                             'key3WithCount_plural': '{{count}} Gegenstände',
-                            'key4': 'Die ausgewählte Sprache ist:'
+                            'key4': 'Die ausgewählte Sprache ist:',
+                            'fruits': ['Apfel', 'Banane', 'Kirsche'],
+                            'steps': [
+                                { 'title': 'Schritt 1', 'text': 'App öffnen' },
+                                { 'title': 'Schritt 2', 'text': 'Klicke auf Start' }
+                            ]
                         }
                     }
                 },
                 lng : 'en',
-                compatibilityJSON: 'v2'
+                compatibilityJSON: 'v2', // important: defines the JSON standard for variable replacement
+                returnObjects: true // set to true if you want to loop over an array or objects of properties
             });
 
         // -- Handlebars' example data object
@@ -130,6 +141,16 @@
             <code>{{{{raw}}}} {{__ "key1" lng="de"}} {{{{/raw}}}}</code>
             <p>&#x2192; {{__ "key1" lng="de"}}</p>
 
+            <h4>Loop over Array of Translations:</h4>
+            <code>
+                {{{{raw}}}} {{#each (__ "fruits")}} {{this}} {{/each}} {{{{/raw}}}}
+            </code>
+            <p><ul>
+            {{#each (__ "fruits")}}
+                <li>{{this}}</li>
+            {{/each}}
+            </ul></p>
+
         <h3>Output selected language</h3>
 
         <button onclick="changeLang()">{{__ "key0"}} {{#if (localeIs "en")}}German {{else}}Englisch {{/if}}</button>
@@ -267,4 +288,4 @@
 
     </script>
 </body>
-</html>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handlebars-i18n",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "handlebars-i18n adds internationalization to handlebars.js using i18next and Intl.",
   "main": "dist/handlebars-i18n.js",
   "scripts": {
@@ -45,7 +45,7 @@
     "@commitlint/cli": "17.6.1",
     "@commitlint/config-conventional": "16.2.1",
     "@types/intl": "^1.2.2",
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.7.0",
     "c8": "^10.1.3",
     "chai": "4.3.6",
     "coveralls-next": "^4.2.1",

package/readme.md

@@ -1,11 +1,8 @@
 # handlebars-i18n
 
-`handlebars-i18n` adds the internationalization features of [i18next](https://www.i18next.com/)
+*What it is about:* `handlebars-i18n` adds the translation features of [i18next](https://www.i18next.com/)
 to [handlebars.js](https://handlebarsjs.com/). It also provides **date**, **number**, and **currency formatting**
-via [Intl](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Intl). Use as node module or in
-the web browser. Supports Typescript.
-
-Handlebars-i18n is listed amongst i18next’s [framework helpers](https://www.i18next.com/overview/supported-frameworks).
+via [Intl](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Intl). Use as node module or in the web browser. `handlebars-i18n` is listed amongst i18next’s official [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-%3E%3D14-brightgreen)
@@ -17,16 +14,22 @@ Handlebars-i18n is listed amongst i18next’s [framework helpers](https://www.i1
 ![npm](https://img.shields.io/npm/dm/handlebars-i18n)
 ![GitHub stars](https://img.shields.io/github/stars/fwalzel/handlebars-i18n?style=social)
 
-## License
 
-Copyright (c) 2020–25 Florian Walzel,
+## Key Features & Advantages
+
+- handlebars-i18n comes lightweight, well tested, and with detailed [examples](#detailed-examples)
+- allows granular custom [presets](#generic-language-format-settings) per language
+- supports Typescript
+- has an optional [CLI](#additional-cli-helper-for-handlebars-i18n-available) for automatic Translations via DeepL
+
 
-MIT License
+## Please Support
 
-If you use handlebars-i18n in a professional context, you could
+`handlebars-i18n` is free but not free of value. If you make serious use of handlebars-i18n, I’d be delighted if you
 
 [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/fwalzel)
 
+
 ## Install
 
 ```sh
@@ -35,17 +38,17 @@ npm i handlebars-i18n
 
 ## Import
 
-Import as commonJS within node environment:
+Import with ES6 syntax:
 
-```javascript
-const HandlebarsI18n = require("handlebars-i18n");
+```typescript
+import HandlebarsI18n from "handlebars-i18n";
 HandlebarsI18n.init();
 ```
 
-With ES6 import syntax:
+As commonJS within node environment:
 
-```typescript
-import * as HandlebarsI18n from "handlebars-i18n";
+```javascript
+const HandlebarsI18n = require("handlebars-i18n");
 HandlebarsI18n.init();
 ```
 
@@ -61,12 +64,12 @@ Usage in web browser (old school):
 </script>
 ```
 
-Via jsDelivr CDN:
+Via CDN:
 ```javascript
-<script src="https://cdn.jsdelivr.net/npm/handlebars-i18n@1.8.3/dist/handlebars-i18n.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/handlebars-i18n@1.10.0/dist/handlebars-i18n.min.js"></script>
 ```
 
-## Quick example
+## Quick Example
 
 Initialize i18next with your language strings and default settings:
 
@@ -88,7 +91,8 @@ i18next.init({
       }
     }
   },
-  lng: "en"
+  lng: "en",
+  compatibilityJSON: 'v2'
 });
 ```
 
@@ -100,7 +104,6 @@ let data = {
   myPrice: 1200.99,
   myDate: "2020-03-11T03:24:00"
 }
-
 ```
 
 Initialize handlebars-i18n:
@@ -120,66 +123,66 @@ HandlebarsI18n.configure([
 
 Finally use in template:
 
-```
+```hbs
 <p> {{__ "phrase1"}} </p>
 ```
 
-* returns for "en" &#x2192; **What is good?**
+* output: en → **What is good?** | de → **Was ist gut?**
 
-```
+```hbs
 <p> {{__ "phrase2" thing=myItem}} </p>
 ```
 
-* returns for "en" &#x2192; **handlebars-i18n is good.**
+* output: en → **handlebars-i18n is good.** | de → **handlebars-i18n ist gut.**
 
-```
+```hbs
 <p> {{_date myDate}} </p>
 ```
 
-* returns for "en" &#x2192; **March 11, 2020, 4:24 AM**
+* output: en → **March 11, 2020 at 3:24 AM** | de → **11.3.2020, 03:24**
 
-```
+```hbs
 <p> {{_price myPrice}} </p>
 ```
 
-* returns for "en" &#x2192; **$1,200.99**
+* output: en → **\$1,200.99** | de → **1.200,99 $**
 
-## Detailed 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.
+- Prompt `npm run example:js` from the root of this repo to log a very basic node example to console.
+- Prompt `npm run example:ts` to compile and log a typescript example.
 
-## Additional CLI Helper for Handlebars-i18n available :metal:
+## Additional CLI Helper for Handlebars-i18n available
 
-Handlebars-i18n has its own command line
+:metal: `handlebars-i18n` has its own command line
 interface [handlebars-i18n-cli](https://www.npmjs.com/package/handlebars-i18n-cli).
 
 ```sh
 npm i handlebars-i18n-cli --save-dev
 ```
 
-Automatically extract translation strings from handlebars templates and generate i18next conform json files from it.
-Handlebars-i18n-cli also helps to keep[](https://) your translations up to date when changes are made in the templates
-over time.
+* programmatically extract/ update translation strings from handlebars templates and generate i18next conform
+  JSON files from it
+* automatic translation of i18next JSON via [DeepL’s](https://www.deepl.com/en/pro-api/) free API
 
-## API
+## Template Functions
 
-### __
+### `__`
 
-Returns the phrase associated with the given key for the selected language. __ will take all options
+Returns the phrase associated with the given key for the selected language. `__` will take all options
 i18next’s [t-function](https://www.i18next.com/overview/api#t) would take.
-The primary key can be passed hard encoded in the template when written in quotes:
+The key can be passed hard encoded in the template when written in quotes:
 
-```
+```hbs
 {{__ "keyToTranslationPhrase"}}
 ```
 
 … or it can be referenced via a handlebars variable:
 
-```
+```hbs
 {{__ keyFromHandlebarsData}}
 ```
 
@@ -187,7 +190,7 @@ The primary key can be passed hard encoded in the template when written in quote
 
 Template usage:
 
-```
+```hbs
 {{__ "whatIsWhat" a="Everything" b="fine"}}
 ```
 
@@ -201,9 +204,11 @@ The i18next resource:
 }
 ```
 
+* output: en → **Everything is fine.**
+
 **Plurals**
 
-```
+```hbs
 {{__ "keyWithCount" count=8}}
 ```
 
@@ -213,194 +218,226 @@ The i18next resource:
     "keyWithCount" : "{{count}} item", 
     "keyWithCount_plural" : "{{count}} items"
   }
-}, 
+}, ...
 ```
 
-**Override globally selected language**
+**Override the globally selected language**
 
-```
+```hbs
 {{__ "key1" lng="de"}}
 ```
 
-Will output the contents for "**de**" even though other language is selected.
+Will output the contents for `de` even though a different language is globally set.
+
+**Looping over an array (or object) of translations**
+
+```hbs
+<ul>
+  {{#each (__ "fruits")}}
+    <li>{{this}}</li>
+  {{/each}}
+</ul>
+```
+In this case the key `fruits` would contain an array of translation strings, like:
+
+```javascript
+{
+  en: {
+    translation: {
+      fruits: ["Apple", "Banana", "Cherry"]
+    }
+  },
+  returnObjects: true
+}
+```
+
+It is recommended to set `returnObjects` actively to `true` in the `i18next.init` object if you want to loop over
+an array or objects of properties.
 
 ---
 
-### _locale
+### `keyExists`
 
-Returns the shortcode of i18next’s currently selected language such as "**en**", "**de**", "**fi**", "**ja**" … etc.
+Checks if a i18next translation key exists. Returns `true` or `false`.
 
+```hbs
+{{#if (keyExists "myKey")}} {{__ "myKey"}} {{/if}}
 ```
+
+---
+
+### `_locale`
+
+Returns the shortcode of i18next’s currently selected language such as `en`, `de`, `ja` … etc.
+
+```hbs
 {{_locale}}
 ```
 
 ---
 
-### localeIs
+### `localeIs`
 
-Checks a string against i18next’s currently selected language. Returns **true** or **false**.
+Checks a string against i18next’s currently selected language. Returns `true` or `false`.
 
-```
+```hbs
 {{#if (localeIs "en")}} ... {{/if}}
 ```
 
 ---
 
-### _date
+### `_date`
 
 Outputs a formatted date according to the language specific conventions.
 
-```
+```hbs
 {{_date}}
 ```
 
 If called without argument the current date is returned. Any other input date can be passed as a conventional date
-string, a number (timestamp in milliseconds), or a date array. _date accepts all arguments
+string, a number (timestamp in milliseconds), or a date array. `_date` accepts all arguments
 Javascript’s [new Date()](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Date)
 constructor would accept.
 
 **Date argument given as date string:**
 
-```
+```hbs
 {{_date "2020-03-11T03:24:00"}}
 ```
 
 or
 
-```
+```hbs
 {{_date "December 17, 1995 03:24:00"}}
 ```
 
 **Date argument given as number (milliseconds since begin of unix epoch):**
 
-```
+```hbs
 {{_date 1583922952743}}
 ```
 
 **Date argument given as javascript date array** [year, monthIndex [, day [, hour [, minutes [,
 seconds [, milliseconds]]]]]]:
 
-```
+```hbs
 {{_date "[2012, 11, 20, 3, 0, 0]"}}
 ```
 
-**Additional arguments for formatting**
+**Additional arguments for formatting:**
 
 You can add multiple arguments for individual formatting.
 See [Intl DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)
 for your option arguments. Alternatively check this repo’s TS types
 in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
 
-```
+```hbs
 {{_date 1583922952743 year="2-digit" day="2-digit" timeZone="America/Los_Angeles"}}
 ```
 
 ---
 
-### _dateAdd :tada: new in 1.8
+### `_dateAdd`
 
 Adds a time offset in a given unit to a date, returns the modified date.
 
-```
+```hbs
 {{_dateAdd "1996-12-17" 24 unit="hour"}}
 ```
 
-Will output for "en" &#x2192; **12/18/1996**
+* output: en → **12/18/1996**
 
-The first argument is a date (see function **_date** for valid date inputs). The second argument is a time amount given 
+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.
+Further options as for function `_date` can be applied.
 
 ---
 
-### _dateDiff
+### `_dateDiff`
 
-Outputs the relative time difference between two given dates.
+Outputs the relative time difference between two given dates in the requested unit.
 
+```hbs
+{{_dateDiff "2000-12-17" "2001-12-17" unit="year"}}
 ```
-{{_dateDiff "1996-12-17T00:00:00" "1995-12-17T00:00:00" unit="year"}}
-```
-
-Will output for "en" &#x2192; **in 1 year**
+* output: en → **in 1 year**
 
 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"`.
+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"`.
 
 ---
 
-### _dateRel 
+### `_dateRel`
 
 Outputs a string with a relative date statement, formatted according to the language specific conventions.
 
-```
+```hbs
 {{_dateRel 7 unit="hour"}}
 ```
 
-Will output for "en" &#x2192; **in 7 hours**
+* output: en → **in 7 hours**
 
-```
+```hbs
 {{_dateRel -7 unit="hour"}}
 ```
 
-Will output for "en" &#x2192; **7 hours ago**
+* output: en → **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"`). 
+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
+### `_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.
 
-```
-{{_num 4100000.8314 }}
+```hbs
+{{_num 3.14159}}
 ```
 
-**Additional arguments for formatting**
+**Additional arguments for formatting:**
 
 You can add multiple arguments for individual formatting.
 See [Intl NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)
 for your option arguments. Alternatively check this repo’s TS types
 in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
 
-```
+```hbs
 {{_num 3.14159 maximumFractionDigits=2}}
 ```
 
-Will output **3.14** for "**en**", but **3,14** for "**de**".
+* output: en → **3.14** | de → **3,14**
 
 ---
 
-### _price
+### `_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.
 
-```
+```hbs
 {{_price 9999.99}}
 ```
 
-**Additional arguments for formatting**
+**Additional arguments for formatting:**
 
 You can add multiple arguments for individual currency formatting.
 See [Intl NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)
 for your option arguments. Alternatively check this repo’s TS types
 in [handlebars-i18n.d.ts](./dist/handlebars-i18n.d.ts).
 
-```
+```hbs
 {{_price 1000 currency="JPY" minimumFractionDigits=2}}
 ```
 
 ---
 
-## How to use HandlebarsI18n.configure method
+## How to use `HandlebarsI18n.configure` method
 
 ### Generic language format settings
 
@@ -411,11 +448,11 @@ all languages or only for specific languages.
 HandlebarsI18n.configure("all", "DateTimeFormat", {timeZone: "America/Los_Angeles"});
 ```
 
-First argument is the language shortcode or "**all**" for all languages. Second is the format option you want to
+First argument is the language shortcode or `"all"` for all languages. Second is the format option you want to
 address (`DateTimeFormat`, `RelativeTimeFormat`, `NumberFormat`, or `PriceFormat`). Third argument is the options object
 with the specific settings.
 
-Examples for generic settings:
+**Examples for generic settings:**
 
 ```javascript
 HandlebarsI18n.configure("all", "RelativeTimeFormat", {style: "long", unit: "second"});
@@ -433,9 +470,9 @@ HandlebarsI18n.configure("all", "PriceFormat", {currency: "HKD", currencyDisplay
 
 You can also define specific subsets to be used in the template, i.e. if you want the date in different formats such as:
 
-- **2020** (year-only)
-- **11.3.2020** (standard-date)
-- **7:24:02** (time-only)
+- **2020** (`year-only`)
+- **11.3.2020** (`standard-date`)
+- **7:24:02** (`time-only`)
 
 To do this, define a 4th parameter with a custom name:
 
@@ -447,9 +484,9 @@ HandlebarsI18n.configure([
 ]);
 ```
 
-Call a subset in template with the parameter format="custom-name", like:
+Call a subset in template with the parameter `format="custom-name"`, like:
 
-```
+```hbs
 {{_date myDate format="year-only"}}
 ```
 
@@ -502,14 +539,14 @@ it instead of the generic Handlebars object like so:
 ```javascript
 const HandlebarsModified = require("handlebars");
 HandlebarsModified.registerHelper("foo", function () {
-  return "what you want"
+  return "bar"
 });
 HandlebarsI18n.init(HandlebarsModified);
 ```
 
-HandlebarsI18n will have your previously defined method **foo()** by now.
+HandlebarsI18n will have your previously defined method `foo` by now.
 
-The same can be done for a custom instance of i18next. Pass it as the second argument to the init function.
+The same can be done for a custom instance of i18next. Pass it as the second argument to the `init` function.
 
 ```javascript
 const i18nextCustom = require("i18next");
@@ -523,12 +560,20 @@ HandlebarsI18n.init(null, i18nextCustom);
 npm test
 ```
 
+## License
+
+MIT License, Copyright (c) 2020–25 Florian Walzel
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
+
 ## Merci à vous
 
 For your contribution, I would like to
 thank [@MickL](https://github.com/MickL), [@dargmuesli](https://github.com/dargmuesli), and [@DiefBell](DiefBell).
 
-## Note
+## Note on alternatives
 
 There is a *different* package named [handlebars-i18next](https://www.npmjs.com/package/handlebars-i18next)
 by [@jgonggrijp](https://github.com/jgonggrijp) which might also suit your needs. Cheers!

package/test/handlebars-i18n.test.js

@@ -19,13 +19,23 @@ describe('handlebars-i18n Tests', function () {
       'en': {
         translation: {
           'key1': 'What is good?',
-          'key2': '{{what}} is {{adverb}}.'
+          'key2': '{{what}} is {{adverb}}.',
+          'fruits': ["Apple", "Banana", "Cherry"],
+          'steps': [
+            { 'title': 'Step 1', 'text': 'Open the app' },
+            { 'title': 'Step 2', text: 'Click start' }
+          ]
         }
       },
       'de': {
         translation: {
           'key1': 'Was ist gut?',
-          'key2': '{{what}} ist {{adverb}}.'
+          'key2': '{{what}} ist {{adverb}}.',
+          'fruits': ["Apfel", "Banane", "Kirsche"],
+          'steps': [
+            { 'title': 'Schritt 1', 'text': 'App öffnen' },
+            { 'title': 'Schritt 2', 'text': 'Klicke auf Start' }
+          ]
         }
       }
     },
@@ -177,6 +187,61 @@ describe('handlebars-i18n Tests', function () {
     assert.equal("handlebarsI18next ist gut.", res.string);
   });
 
+  it("__ should loop over array of strings with #each", () => {
+    i18next.changeLanguage('en');
+    const template = Handlebars.compile(`
+      <ul>
+        {{#each (__ "fruits")}}
+          <li>{{this}}</li>
+        {{/each}}
+      </ul>
+    `);
+
+    const output = template({});
+    console.log(output);
+    expect(output).to.contain("Apple");
+    expect(output).to.contain("Banana");
+    expect(output).to.contain("Cherry");
+  });
+
+  it("__ should loop over array of objects with #each", () => {
+    const template = Handlebars.compile(`
+      <ol>
+        {{#each (__ "steps")}}
+          <li><strong>{{title}}</strong>: {{text}}</li>
+        {{/each}}
+      </ol>
+    `);
+
+    const output = template({});
+    expect(output).to.contain("<strong>Step 1</strong>: Open the app");
+    expect(output).to.contain("<strong>Step 2</strong>: Click start");
+  });
+
+
+  /****************************************
+   Tests against function keyExists
+   ****************************************/
+
+  it('should return true for an existing translation key', function() {
+    const exists = hI18n.helpers.keyExists('key1');
+    assert.isTrue(exists);
+  });
+
+  it('should return false for a non-existing translation key', function() {
+    const exists = hI18n.helpers.keyExists('nonExistentKey');
+    assert.isFalse(exists);
+  });
+
+  it('should return false when called with no parameters', function() {
+    const exists = hI18n.helpers.keyExists();
+    assert.isFalse(exists);
+  });
+
+  it('should return false when called with null or undefined', function() {
+    assert.isFalse(hI18n.helpers.keyExists(null));
+    assert.isFalse(hI18n.helpers.keyExists(undefined));
+  });
 
   /****************************************
    Tests against function _date
@@ -1165,4 +1230,4 @@ describe('handlebars-i18n Private helper Function Tests (in production not expor
     expect(result).to.deep.equal({});
   });
 
-});
+});