JS-DSI18n/i18n.js

'use strict';

/*
    Internationalization Class for JavaScript
    Copyright (C) 2018 Michael Fabian 'Xaymar' Dirks <info@xaymar.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published
    by the Free Software Foundation, version 3 of the License.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.
*/

/*
Dead Simple I18n Library

Languages are stored in a Map() to allow for any kind of name to be used. In
 addition to that there is a global base language, and each language can 
 specify an override base language which will be used only if that language
 is actually loaded during translation. The base language can be an array
 instead of a string, in which each language is tested in order of appearance.

The key can only be a string, while the Value is allowed to be anything. In
 case you want to implement pluralization in your translation layer, you would
 be doing it with an object value or similar. This creates a simple structure
 that can be used for various kinds of translations, and is as fast as the
 underlying Map implementation.

# Example: Evaluation of the language chain [en-US < en-GB < de-DE < de-BE]
Searching for the key will first happen in de-BE, then in de-DE, then in en-GB
 and finally in en-US. If de-BE, de-DE or en-GB is not loaded, that specific
 lookup step skips straight to the global base language, in this case en-US. If
 en-US is not loaded, the original i18n key is returned instead.

# Example: Evaluation of the language chain [en-US < en-GB < de-DE, en-GB < de-BE]
Checks first happen in de-BE, if de-BE does not have the key checks move on to
 de-DE. If de-DE is not loaded, en-GB is instead checked. If de-DE does not
 have the key, checks progress to en-GB. If en-GB does not have the key, checks
 progress to en-US. If any of them are not loaded or does not have the key, the
 next language in the base languages is checked, until the base languages are
 exhausted, in which case the i18n key is returned.

# Structure
Map{
    languageName: Map{
        // Base language override (optional)
        _base: {string},
        // Key Value storage for lookup
        {string key}: {any value},
    }
}

# Internal behavior
The library will build a chain of languages to check in a loop for, to avoid
 costly recursive calls that aren't well protected against loops in base
 language definitions (i.e. de-DE depends on en-GB, en-GB depends on de-DE).
This cache is refreshed when first attempting to translate to that language,
 and flagged as dirty every time a language is loaded or a base language is
 changed.

*/

class I18n {
	/** Create a new object, ready to be used.
     * 
     * @param {string} defaultLanguage Initial base language to base all translations on.
     * @param {string} baseLanguageKey Key to use for base language overrides. (Default = _base)
     * @throws Exception on invalid parameters.
     */
	constructor(defaultLanguage, baseLanguageKey = '_base') {
		this._sanitizeLanguage(defaultLanguage);
		this._verifyKey(baseLanguageKey);

		this.languages = new Map();
		this.chains = new Map();
		this.baseLanguage = defaultLanguage;
		this.baseLanguageKey = baseLanguageKey;

		this.dirtyTs = performance.now();
		this.chainsTs = performance.now();
	}

	/** Update the global base language.
	 * 
	 * @param {string} language 
	 */
	setBaseLanguage(language) {
		this._sanitizeLanguage(language);
		this.baseLanguage = language;
		this.dirtyTs = performance.now();
	}

	/** Retrieve the global base language.
	 * 
	 * @return {string} name of base language.
	 */
	getBaseLanguage() {
		return this.baseLanguage;
	}

	/** Check if a language is known.
     * 
     * @param {string} language Name of the language
     * @returns {bool} true if known.
     */
	hasLanguage(language) {
		language = this._sanitizeLanguage(language);
		return this.languages.has(language);
	}

	/** Create a new language.
     * 
     * @param {string} language Name of the language.
     * @throws Exception on invalid parameters.
     */
	createLanguage(language) {
		language = this._sanitizeLanguage(language);
		this.languages.set(language, new Map());
		this.dirtyTs = performance.now();
	}

	/** Load a new language.
     * 
     * @param {string} language Name of the language.
	 * @param {File/Blob/object/string} data Data containing a JSON representation of the language.
     * @param {string} encoding (Optional) Encoding to use when reading File or Blob.
     * @returns {Promise}
     * @throws Exception on invalid parameters or invalid data.
     */
	loadLanguage(language, data, encoding = 'utf-8') {
		// Verify input.
		language = this._sanitizeLanguage(language);
		this._verifyData(data);

		return new Promise((resolve, reject) => {
			// Decode data from various forms.
			let decodePromise;
			if ((data instanceof File) || (data instanceof Blob)) {
				decodePromise = new Promise((fileResolve, fileReject) => {
					let freader = new FileReader();
					freader.onload(() => {
						fileResolve(JSON.parse(freader.result));
					});
					freader.onabort((ev) => {
						fileReject(ev);
					});
					freader.onerror((ev) => {
						fileReject(ev);
					});
					freader.readAsText(data, encoding);
				});
			} else if (typeof(data) == 'string') {
				decodePromise = new Promise((parseResolve, parseReject) => {
					parseReject;
					parseResolve(JSON.parse(data));
				});
			} else if (typeof(data) == 'object') {
				decodePromise = new Promise((passResolve, passReject) => {
					passReject;
					passResolve(data);
				});
			} else {
				reject('invalid data');
			}

			// Load Data
			decodePromise.then((result) => {
				let language_map = new Map();
				for (let key in result) {
					language_map.set(key, result[key]);
				}

				this.languages.set(language, language_map);
				this.dirtyTs = performance.now();
				resolve(language);
			}, (reason) => {
				reject(reason);
			});
		});
	}

	/** Save a language.
     * 
     * @param {string} language Name of the language.
     * @returns {Promise} Promise that eventually returns the JSON data of the language.
     * @throws Exception on invalid parameters and missing language.
     */
	saveLanguage(language) {
		language = this._sanitizeLanguage(language);
		this._verifyLanguageKnown(language);

		return new Promise((resolve, reject) => {
			reject;
			this._verifyLanguageKnown(language);

			let language_data = {};
			let language_map = this.languages.get(language);
			language_map.forEach((value, key, map) => {
				map;
				language_data[key] = value;
			});
			let json_data = JSON.stringify(language_data);
			resolve(json_data);
		});
	}

	/** Destroy/unload a language.
     * 
     * @param {string} language Name of the language.
     * @throws Exception on invalid parameters and missing language.
     */
	destroyLanguage(language) {
		language = this._sanitizeLanguage(language);
		this._verifyLanguageKnown(language);

		this.languages.delete(language);
		this.dirtyTs = performance.now();
	}

	/** Clear a key from a language.
     * 
     * @param {string} language Language to edit.
     * @param {string} key Key to clear.
     * @return {bool} true on success.
     * @throws Exception on invalid parameters and missing language.
     */
	clearKey(language, key) {
		// Verify and sanitize input.
		language = this._sanitizeLanguage(language);
		this._verifyKey(key);

		// Check if language exists.
		this._verifyLanguageKnown(language);

		// Delete key if exists.
		let language_map = this.languages.get(language);
		if (!language_map.has(key)) {
			return false;
		}
		language_map.delete(key);

		// If the key was the base language key, set dirty timestamp.
		if (key == this.baseLanguageKey) {
			this.dirtyTs = performance.now();
		}

		return true;
	}

	/** Set a key in a language
     * 
     * @param {string} language Language to edit.
     * @param {string} key Key to set.
     * @param {*} value New value to set.
     * @param {bool} force Force the update if the key exists. (Default = true)
     * @return {bool} true on success.
     * @throws Exception on invalid parameters and missing language.
     */
	setKey(language, key, value, force = true) {
		// Verify and sanitize input.
		language = this._sanitizeLanguage(language);
		this._verifyKey(key);

		// Check if language exists.
		this._verifyLanguageKnown(language);

		// Set key.
		let language_map = this.languages.get(language);
		if ((language_map.has(key)) && !force) {
			return false;
		}
		language_map.set(key, value);

		// If the key was the base language key, set dirty timestamp.
		if (key == this.baseLanguageKey) {
			this.dirtyTs = performance.now();
		}

		return true;
	}

	/** Get a key in a language
     * 
     * @param {string} language 
     * @param {string} key 
     * @return {*} the value
     * @throws Exception on invalid parameters, missing language and missing key.
     */
	getKey(language, key) {
		// Verify and sanitize input.
		language = this._sanitizeLanguage(language);
		this._verifyKeyKnown(language, key);

		// Get Key
		let language_map = this.languages.get(language);
		return language_map.get(key);
	}

	/** Translate a single string to any loaded language.
     * 
     * @param {string} key String to translate
     * @param {string} language Language to translate to
     * @return {string} Translated string, or if failed the string plus the language appended.
     * @throws Exception on invalid parameters.
     */
	translate(key, language) {
		// Verify and sanitize input.
		language = this._sanitizeLanguage(language);
		this._verifyKey(key);

		// Translate using the translation chain.
		let chain = this._cacheChain(language);
		let translated = key;
		for (let language of chain) {
			let languageMap = this.languages.get(language);
			if (languageMap.has(key)) {
				translated = languageMap.get(key);
				break;
			}
		}

		return translated;
	}

	/** Automatically translate the entire page using the specified property on elements.
     * 
     * @param {string} language Language to translate to
     * @param {string} property Property to search for (default 'data-i18n')
     * @param {function} resolver Function to call to find the proper translation, called with parameters ({string}language, {string}key, {Node}element) and must return a string.
     * @param {function} applier Function to call to apply the proper translation, called with parameters ({string}language, {string}key, {string}translation, {Node}element) and must return a boolean.
     * @returns {Promise} resolved when successful, rejected if applier returns false.
     * @throws Exception on invalid parameters.
     */
	domTranslate(language, property = 'data-i18n', resolver = undefined, applier = undefined) {
		language = this._sanitizeLanguage(language);
		if ((resolver != undefined) && (typeof (resolver) != 'function')) {
			throw 'resolver must be a function';
		} else if (resolver == undefined) {
			let self = this;
			resolver = (language, key, el) => {
				return self._defaultResolver(language, key, el);
			};
		}
		if ((applier != undefined) && (typeof (applier) != 'function')) {
			throw 'applier must be a function';
		} else if (applier == undefined) {
			let self = this;
			applier = (language, key, translation, el) => {
				return self._defaultApplier(language, key, translation, el);
			};
		}

		return new Promise((resolve, reject) => {
			let els = document.querySelectorAll(`[${property}]`);
			for (let el of els) {
				let key = el.getAttribute(property);
				if (!applier(language, key, resolver(language, key, el), el)) {
					reject();
					return;
				}
			}
			resolve();
		});
	}
	
	// Private Functions
	_verifyLanguageKnown(language) {
		if (!this.languages.has(language)) {
			throw 'language unknown';
		}
	}

	_verifyKey(key) {
		if (typeof (key) == 'string') {
			return;
		}
		throw 'key must be of type string';
	}

	_verifyKeyKnown(language, key) {
		this._verifyLanguageKnown(language);
		this._verifyKey(key);

		if (!this.languages.get(language).has(key)) {
			throw 'key unknown in language';
		}
	}

	_verifyData(data) {
		if (typeof (data) == 'string') {
			return;
		}
		if (typeof (data) == 'object') {
			return;
		}
		if (data instanceof File) {
			return;
		}
		if (data instanceof Blob) {
			return;
		}
		throw 'data must be of type string, object, File or Blob';
	}

	_sanitizeLanguage(language) {
		try {
			this._verifyKey(language);
		} catch (e) {
			throw 'language must be of type string';
		}
		return language.toLowerCase();
	}

	_defaultResolver(language, key, element) {
		element;
		return this.translate(key, language);
	}

	_defaultApplier(language, key, translation, element) {
		try {
			element.textContent = translation;
			return true;
		} catch (e) {
			return false;
		}
	}

	/** Caches the necessary language chain for translation.
     * 
     * Creates and returns a language chain required for translation, avoiding
     *  recursive loops that never end in the process. The chain will not 
     *  evalute the entire branch first, instead it will check all branches
     *  and then list the childs of those branches. This is an expensive
     *  operation and should only be done once on every language update.
     * 
     * Example:
     *  de-DE +- en-GB - en-US - de-DE (- en-GB, en-US, ... [recursive])
     *        \- en-US - de-DE (- en-GB, en-US, ... [recursive])
     * Result: [de-DE, en-GB, en-US]
     * Explanation: de-DE depends on both en-GB and en-US, and will check both
     *  before considering the next branch. Since all dependencies are resolved
     *  early, a recursive lookup is prevented here.
     * 
     * Example:
     *  de-BE +- de-DE - en-GB - en-US 
	 *        +- en-GB - en-US
	 *        +- de-AU - de-DE - en-GB - en-US
	 *        +- en-US
	 * Result: [de-Be, de-DE, en-GB, de-AU, en-US]
	 * Explanation: de-BE depends on [de-DE, en-GB, de-AU, en-US], resolving 
	 *  de-DE returns en-GB (if loaded), which we already have. en-GB resolves
	 *  to en-US, which we also already have. de-AU resolves to de-DE, also 
	 *  known. And finally en-US resolves to nothing as the global base language.
     * 
     * @param {string} language 
     * @returns {array} Translation chain
     */
	_cacheChain(language) {
		// This caches a chain so that we do not have to rebuild this every
		//  lookup. It is important that there are no recursive loops in this
		//  code, which means we can't rely on this function to work until the
		//  cache is completed.

		// Have there been changes to the timestamp?
		if (this.chainsTs < this.dirtyTs) {
			// If yes, clear all chains for rebuilding.
			this.chainsTs = this.dirtyTs;
			this.chains.clear();
		}

		// Do we have a chain cached?
		if (this.chains.has(language)) {
			// Yes, return the cached chain and go back to translation.
			return this.chains.get(language);
		}

		// Create a new chain without relying on our own function.
		let chain = new Array();
		chain.push(language); // Chains always contain the language itself.

		// Now we walk through the chain manually, modifying it as we go.
		for (let pos = 0; pos < chain.length; pos++) {
			// Check if the language is loaded, if not skip it.
			if (!this.languages.has(chain[pos])) {
				continue;
			}
			let languageMap = this.languages.get(chain[pos]);

			// Check if there is a base language override.
			if (!languageMap.has(this.baseLanguageKey)) {
				continue;
			}
			let baseLanguages = languageMap.get(this.baseLanguageKey);

			// Convert to array for for...in.
			if (typeof (baseLanguages) == 'string') {
				baseLanguages = [baseLanguages];
			} else if (!(baseLanguages instanceof Array)) {
				continue;
			}

			for (let base of baseLanguages) {
				base = this._sanitizeLanguage(base);
				if (!chain.includes(base) && (this.languages.has(base))) {
					chain.push(base);
				}
			}
            
			// Append the global base languages if there are no other languages left.
			if (pos == (chain.length - 1)) {
				let baseLanguages = this.baseLanguage;
				if (typeof(this.baseLanguage) == 'string') {
					baseLanguages = [this.baseLanguage];
				}
				for (let base of baseLanguages) {
					if (!chain.includes(base) && (this.languages.has(base))) {
						chain.push(base);
					}
				}
			}
		}

		// Store.
		this.chains.set(language, chain);

		// Return.
		return chain;
	}
}

// Compatible with Node.js and Browsers
if (typeof (module) != 'undefined') {
	module.exports = exports = {
		'I18n': I18n
	};
}