@schukai/monster 1.25.0 → 1.28.0

package/source/i18n/formatter.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+
+
+import {internalSymbol} from "../constants.js";
+import {extend} from "../data/extend.js";
+import {assignToNamespace, Monster} from '../namespace.js';
+import {Formatter as TextFormatter} from "../text/formatter.js";
+import {validateInstance, validateString} from "../types/validate.js";
+import {Translations} from "./translations.js";
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const internalTranslationSymbol = Symbol('internalTranslation')
+
+/**
+ * The Formatter extends the Text.Formatter with the possibility to replace the key by a translation.
+ *
+ * You can create an instance via the monster namespace `new Monster.I18n.Formatter()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
+ * new Monster.I18n.Formatter()
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {Formatter} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/formatter.js';
+ * new Formatter()
+ * </script>
+ * ```
+ *
+ * @example
+ *
+ * import {Formatter} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/formatter.js';
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/translations.js';
+ *
+ * const translations = new Translations('en')
+ *     .assignTranslations({
+ *         thekey: "${animal} has eaten the ${food}!"
+ *     });
+ *
+ * new Formatter({}, translations).format("thekey:animal=dog::food=cake")
+ * // ↦ dog has eaten the cake!
+ *
+ * @since 1.26.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.I18n
+ */
+class Formatter extends TextFormatter {
+
+    /**
+     * Default values for the markers are `${` and `}`
+     *
+     * @param {object} object
+     * @throws {TypeError} value is not a object
+     */
+    constructor(object, translation, options) {
+        super(object, options);
+        this[internalTranslationSymbol] = validateInstance(translation, Translations);
+    }
+
+    /**
+     * @property {object} marker
+     * @property {array} marker.open=["i18n{","${"]
+     * @property {array} marker.close=["${"]
+     * @property {object} parameter
+     * @property {string} parameter.delimiter="::"
+     * @property {string} parameter.assignment="="
+     * @property {object} callbacks
+     * @property {function} callbacks.i18n=()=>{}
+     */
+    get defaults() {
+        const self = this;
+        return extend({}, super.defaults, {
+            callbacks: {
+                i18n: (value) => {
+                    return self[internalTranslationSymbol].getText(validateString(value));
+                }
+            },
+            marker: {
+                open: ['i18n{', '${'],
+                close: ['}'],
+            },
+        })
+    }
+
+    /**
+     *
+     * @param {string} text
+     * @return {string}
+     * @throws {TypeError} value is not a string
+     * @throws {Error} too deep nesting
+     * @throws {Error} key not found
+     * @throws {Error} the closing marker is missing
+     */
+    format(text) {
+        validateString(text)
+
+        const openMarker = this[internalSymbol]['marker']['open']?.[0];
+        const closeMarker = this[internalSymbol]['marker']['close']?.[0];
+
+        if (text.indexOf(openMarker) === 0) {
+            text = text.substring(openMarker.length);
+
+            if (text.indexOf(closeMarker) === text.length - closeMarker.length) {
+                text = text.substring(0, text.length - closeMarker.length);
+            } else {
+                throw new Error("the closing marker is missing")
+            }
+        }
+
+
+        const parts = validateString(text).split('::')
+        const translationKey = parts.shift().trim(); // key value delimiter
+        const parameter = parts.join('::').trim();
+
+
+        let assembledText = openMarker + 'static:' + translationKey + ' | call:i18n';
+        if (parameter.length > 0) {
+            assembledText += '::' + parameter;
+        }
+        assembledText += closeMarker;
+        return super.format(assembledText);
+    }
+
+
+}
+
+assignToNamespace('Monster.I18n', Formatter);
+export {Monster, Formatter}

package/source/i18n/locale.js

@@ -25,7 +25,7 @@ const localeStringSymbol = Symbol('localeString');
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/locale.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.I18n.Locale()
  * </script>
  * ```
@@ -34,7 +34,7 @@ const localeStringSymbol = Symbol('localeString');
  *
  * ```
  * <script type="module">
- * import {Locale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/locale.js';
+ * import {Locale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/locale.js';
  * new Locale()
  * </script>
  * ```
@@ -172,6 +172,8 @@ class Locale extends Base {
     }
 
     /**
+     * The structure has the following: language, script, region, variants, extlang, privateUse
+     *
      * @return {Monster.I18n.LocaleMap}
      */
     getMap() {
@@ -201,7 +203,7 @@ class Locale extends Base {
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/locale.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.I18n.createLocale()
  * </script>
  * ```
@@ -210,7 +212,7 @@ class Locale extends Base {
  *
  * ```
  * <script type="module">
- * import {createLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/locale.js';
+ * import {createLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/locale.js';
  * createLocale()
  * </script>
  * ```

package/source/i18n/provider.js

@@ -15,7 +15,7 @@ import {Translations} from "./translations.js"
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/provider.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.I18n.Provider()
  * </script>
  * ```
@@ -24,7 +24,7 @@ import {Translations} from "./translations.js"
  *
  * ```
  * <script type="module">
- * import {Provider} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/provider.js';
+ * import {Provider} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/provider.js';
  * new Provider()
  * </script>
  * ```

package/source/i18n/providers/fetch.js

@@ -22,7 +22,7 @@ import {Translations} from "../translations.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/providers/fetch.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.I18n.Providers.Fetch()
  * </script>
  * ```
@@ -31,21 +31,36 @@ import {Translations} from "../translations.js";
  *
  * ```
  * <script type="module">
- * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/providers/fetch.js';
+ * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/providers/fetch.js';
  * new Fetch()
  * </script>
  * ```
+ * 
+ * @example <caption>das ist ein test</caption>
+ * 
+ * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/providers/fetch.js';
+ * 
+ * // fetch from API
+ * const translation = new Fetch('https://example.com/${language}.json').getTranslation('en-GB');
+ * // ↦ https://example.com/en.json
  *
  * @since 1.13.0
  * @copyright schukai GmbH
  * @memberOf Monster.I18n.Providers
  * @see {@link https://datatracker.ietf.org/doc/html/rfc3066}
+ * @tutorial i18n-locale-and-formatter
  */
 class Fetch extends Provider {
 
     /**
      * As options the key `fetch` can be passed. This config object is passed to the fetch method as init.
-     *
+     * 
+     * The url may contain placeholders (language, script, region, variants, extlang, privateUse), so you can specify one url for all translations.
+     * 
+     * ```
+     * new Fetch('https://www.example.com/assets/${language}.json')
+     * ```
+     * 
      * @param {string|URL} url
      * @param {Object} options see {@link Monster.I18n.Providers.Fetch#defaults}
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/fetch}

package/source/i18n/translations.js

@@ -17,7 +17,7 @@ import {Locale, parseLocale} from "./locale.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/translations.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.I18n.Translations()
  * </script>
  * ```
@@ -26,23 +26,33 @@ import {Locale, parseLocale} from "./locale.js";
  *
  * ```
  * <script type="module">
- * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/translations.js';
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/translations.js';
  * new Translations()
  * </script>
  * ```
  *
  * @example
  *
- * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/i18n/translations.js';
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/translations.js';
+ * import {parseLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/i18n/locale.js';
+ *
  * const translation = new Translations(parseLocale('en-GB'));
  *
  * translation.assignTranslations({
- *            text1: "abc",
- *            text2: {'other': 'xyz'}
- *         });
+ *           text1: "click",
+ *           text2: {
+ *             'one': 'click once',
+ *             'other': 'click n times'
+ *           }
+ *        });
+ *
+ * console.log(translation.getText('text1'));
+ * // ↦ click
  *
- * translation.getText('text1);
- * translation.getPluralRuleText('text2',2);
+ * console.log(translation.getPluralRuleText('text2',1));
+ * // -> click once
+ * console.log(translation.getPluralRuleText('text2',2));
+ * // -> click n times
  *
  * @since 1.13.0
  * @copyright schukai GmbH
@@ -205,6 +215,5 @@ class Translations extends Base {
 
 }
 
-
 assignToNamespace('Monster.I18n', Translations);
 export {Monster, Translations}

package/source/logging/handler/console.js

@@ -15,7 +15,7 @@ import {LogEntry} from "../logentry.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/handler/console.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * console.log(new Monster.Logging.Handler.ConsoleHandler())
  * </script>
  * ```
@@ -24,7 +24,7 @@ import {LogEntry} from "../logentry.js";
  *
  * ```
  * <script type="module">
- * import {ConsoleHandler} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/handler/console.js';
+ * import {ConsoleHandler} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/logging/handler/console.js';
  * console.log(new ConsoleHandler())
  * </script>
  * ```

package/source/logging/handler.js

@@ -15,7 +15,7 @@ import {ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN} from "./logger.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/handler.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * console.log(new Monster.Logging.Handler())
  * </script>
  * ```
@@ -24,7 +24,7 @@ import {ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN} from "./logger.js";
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/handler.js';
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/logging/handler.js';
  * console.log(new Handler())
  * </script>
  * ```

package/source/logging/logentry.js

@@ -14,7 +14,7 @@ import {validateInteger} from '../types/validate.js';
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/logentry.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * console.log(new Monster.Logging.LogEntry())
  * </script>
  * ```
@@ -23,7 +23,7 @@ import {validateInteger} from '../types/validate.js';
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/logentry.js';
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/logging/logentry.js';
  * console.log(new LogEntry())
  * </script>
  * ```

package/source/logging/logger.js

@@ -65,7 +65,7 @@ const OFF = 0;
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/logger.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * new Monster.Logging.Logger()
  * </script>
  * ```
@@ -74,7 +74,7 @@ const OFF = 0;
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/logging/logger.js';
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/logging/logger.js';
  * new Logger()
  * </script>
  * ```

package/source/math/random.js

@@ -15,7 +15,7 @@ import {getGlobal} from '../types/global.js';
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/math/random.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * Monster.Math.random(1,10)
  * // ↦ 5
  * </script>
@@ -25,7 +25,7 @@ import {getGlobal} from '../types/global.js';
  *
  * ```
  * <script type="module">
- * import {random} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/math/random.js';
+ * import {random} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/modules/math/random.js';
  * random(1,10)
  * // ↦ 5
  * </script>

package/source/namespace.js

@@ -65,7 +65,7 @@ export const Monster = new Namespace("Monster");
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/namespace.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.28.0/dist/monster.js';
  * function hello() {
  *            console.log('Hello World!');
  *        }