/** * Copyright schukai GmbH and contributors 2022. All Rights Reserved. * Node module: @schukai/monster * This file is licensed under the AGPLv3 License. * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html */ import {Base} from "../types/base.mjs"; import {isObject, isString} from "../types/is.mjs"; import {validateInstance, validateInteger, validateObject, validateString} from "../types/validate.mjs"; import {Locale, parseLocale} from "./locale.mjs"; export {Translations} /** * With this class you can manage translations and access the keys. * * @externalExample ../../example/i18n/translations.mjs * @license AGPLv3 * @since 1.13.0 * @copyright schukai GmbH * @memberOf Monster.I18n * @see https://datatracker.ietf.org/doc/html/rfc3066 */ class Translations extends Base { /** * * @param {Locale} locale */ constructor(locale) { super(); if (isString(locale)) { locale = parseLocale(locale); } this.locale = validateInstance(locale, Locale); this.storage = new Map(); } /** * Fetches a text using the specified key. * If no suitable key is found, `defaultText` is taken. * * @param {string} key * @param {string|undefined} defaultText * @return {string} * @throws {Error} key not found */ getText(key, defaultText) { if (!this.storage.has(key)) { if (defaultText === undefined) { throw new Error('key ' + key + ' not found'); } return validateString(defaultText); } let r = this.storage.get(key); if (isObject(r)) { return this.getPluralRuleText(key, 'other', defaultText); } return this.storage.get(key); } /** * A number `count` can be passed to this method. In addition to a number, one of the keywords can also be passed directly. * "zero", "one", "two", "few", "many" and "other". Remember: not every language has all rules. * * The appropriate text for this number is then selected. If no suitable key is found, `defaultText` is taken. * * @param {string} key * @param {integer|count} count * @param {string|undefined} defaultText * @return {string} */ getPluralRuleText(key, count, defaultText) { if (!this.storage.has(key)) { return validateString(defaultText); } let r = validateObject(this.storage.get(key)); let keyword; if (isString(count)) { keyword = count.toLocaleString(); } else { count = validateInteger(count); if (count === 0) { // special handlig for zero count if (r.hasOwnProperty('zero')) { return validateString(r['zero']); } } keyword = new Intl.PluralRules(this.locale.toString()).select(validateInteger(count)); } if (r.hasOwnProperty(keyword)) { return validateString(r[keyword]); } if (r.hasOwnProperty(DEFAULT_KEY)) { return validateString(r[DEFAULT_KEY]); } return validateString(defaultText); } /** * Set a text for a key * * ``` * translations.setText("text1": "Make my day!"); * // plural rules * translations.setText("text6": { * "zero": "There are no files on Disk.", * "one": "There is one file on Disk.", * "other": "There are files on Disk." * "default": "There are files on Disk." * }); * ``` * * @param {string} key * @param {string|object} text * @return {Translations} * @throws {TypeError} value is not a string or object */ setText(key, text) { if (isString(text) || isObject(text)) { this.storage.set(validateString(key), text); return this; } throw new TypeError('value is not a string or object'); } /** * This method can be used to transfer overlays from an object. The keys are transferred, and the values are entered * as text. * * The values can either be character strings or, in the case of texts with plural forms, objects. The plural forms * must be stored as text via a standard key "zero", "one", "two", "few", "many" and "other". * * Additionally, the key default can be specified, which will be used if no other key fits. * * In some languages, like for example in German, there is no own more number at the value 0. In these languages, * the function applies additionally zero. * * ``` * translations.assignTranslations({ * "text1": "Make my day!", * "text2": "I'll be back!", * "text6": { * "zero": "There are no files on Disk.", * "one": "There is one file on Disk.", * "other": "There are files on Disk." * "default": "There are files on Disk." * }); * ``` * * @param {object} translations * @return {Translations} */ assignTranslations(translations) { validateObject(translations); for (const [k, v] of Object.entries(translations)) { this.setText(k, v); } return this; } }