/*
Copyright (C) 2016 PencilBlue, LLC
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
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 General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
'use strict';
//dependencies
var fs = require('fs');
var path = require('path');
var Locale = require('locale');
var util = require('./util.js');
module.exports = function LocalizationModule(pb) {
//pb dependencies
var config = pb.config;
/**
* Provides functions to translate items based on keys. Also
* assists in the determination of the best language for the given user.
*
* @module Services
* @class Localization
* @constructor
* @param {Request|string} request The request object
* @param {Object} [options]
* @param {String} [options.activeTheme]
* @param {Array} [options.supported] The languages that the localization
* instance should be limited to.
*/
function Localization(request, options){
if (!util.isObject(options)) {
options = {};
}
/**
* expected to be lowercase and of the form "en-us"
* @property language Really should be renamed to locale in the future
* @type {String}
*/
this.language = Localization.best(request, options.supported).toString();
/**
* @property localeObj
* @type {Object}
*/
this.localeObj = Localization.parseLocaleStr(this.language);
/**
* Stores the keys already retrieved for the instance to prevent duplicate retrieval.
* @property cache
* @type {Object}
*/
this.cache = {};
/**
* The currently active theme that should be prioritized when
* performing key lookup
* @property activeTheme
* @type {string}
*/
this.activeTheme = options.activeTheme;
}
/**
*
* @property JS_EXT
* @type {String}
*/
var JS_EXT = '.js';
/**
*
* @static
* @readonly
* @property SEP
* @type {String}
*/
Localization.SEP = '^';
/**
*
* @static
* @readonly
* @property PREFIX
* @type {String}
*/
Localization.PREFIX = Localization.SEP + 'loc_';
/**
*
* @static
* @readonly
* @property ACCEPT_LANG_HEADER
* @type {String}
*/
Localization.ACCEPT_LANG_HEADER = 'accept-language';
/**
*
* @static
* @readonly
* @property LOCALE_PART_SEP
* @type {String}
*/
Localization.LOCALE_PART_SEP = '-';
/**
*
* @static
* @readonly
* @property KEY_SEP
* @type {String}
*/
Localization.KEY_SEP = '.';
/**
*
* @static
* @readonly
* @property storage
* @type {Object}
*/
Localization.storage = {};
/**
*
* @static
* @readonly
* @property supported
* @type {Locales}
*/
Localization.supported = null;
/**
* @static
* @readonly
* @property supportedLookup
* @type {Object}
*/
Localization.supportedLookup = {};
/**
* @static
* @readonly
* @property PARAM_REPLACEMENT_REGEX
* @type {RegExp}
*/
Localization.PARAM_REPLACEMENT_REGEX = /{([^{}]*)}/g;
/**
* Localizes a string by searching for keys within the template and replacing
* them with the specified values.
* @deprecated
* @method localize
* @param {Array} sets The localizations sets to search in
* @param {string} text The text to localize
* @param {string} hostname The current hostname
* @return {string} The text where keys have been replaced with translated values
*/
Localization.prototype.localize = function(sets, text, hostname){
if (pb.log.isSilly()) {
pb.log.silly('Localization: Localizing text - Locale [%s] Sets %s', this.language, JSON.stringify(sets));
}
pb.log.warn('Localization: localize is deprecated and will be removed in 1.0. Place your localizations in templates');
//get i18n from storage
var loc = Localization.storage;
if (util.isNullOrUndefined(loc)) {
throw new Error("Failed to set a language. LANG="+util.inspect(this.language));
}
//to squeeze a little performance out of an outdated function we convert the sets to a quick lookup to reduce
// the number of comparisons necessary to see if we should even check for a localization
var self = this;
var superSets = ['generic'];
util.arrayPushAll(sets, superSets);
var setLookup = superSets.reduce(function(lookup, prefix) {
lookup[prefix] = true;
return lookup;
}, {});
text = Object.keys(Localization.storage).reduce(function(content, key) {
//look to see if the set even matches
var pieces = key.split('.');
//see if the set matches only when the set is in the lookup and when the key is nested (backward compatibility piece)
if (pieces.length === 1 || !setLookup[pieces[0]]) {
return content;
}
var setVal = self.g(key/*, {empty options}*/);
return content.split('^loc_' + pieces[1] + '^').join(setVal);
}, text);
// If the localization is for HTML output, load the localization into client side JS
if (text.indexOf('<body') >= 0) {
text = text.concat(pb.ClientJs.includeJS(pb.UrlService.createSystemUrl('api/localization/script?locale=' + this.language, { hostname: hostname })));
}
return text;
};
/**
* Translates a single key. The function accepts a variable number of
* parameters. The first must be the key to be localized. The rest are
* considered to be injectable values. The function will call "util.format" in
* situations where the key is found and the nuber of arguments passed to the
* function is greater than 1. See
* http://nodejs.org/api/util.html#util_util_format_format for details on
* supported formatting.
* @deprecated Since 0.5.0
* @method get
* @param {String} key
* @param {String|Integer|Number|Object} [args] The variable number of
* parameters to be injected into the localization value
* @return {string|null} The formatted and localized string
*/
Localization.prototype.get = function() {
var key = arguments[0];
if (pb.log.isSilly()) {
pb.log.silly('Localization: Localizing key [%s] - Locale [%s]', key, this.language);
}
//error checking
if (!pb.validation.isNonEmptyStr(key, true)) {
return null;
}
//create a key that can be converted over to what we need
var convertedKey = key;
if (util.isNullOrUndefined(Localization.storage[key])) {
//now we must loop over the keys to see if we were given only the second half of a localization key
//this is extremely inefficient and hence why the function is deprecated
var keys = Object.keys(Localization.storage);
for (var i = 0; i < keys.length; i++) {
//check to see if the the key is partitioned
var index = keys[i].indexOf('.');
if (index < 0) {
continue;
}
//now we check to see if we were only given the second half of the localization key
if (keys[i].substr(index + 1) === key) {
convertedKey = keys[i];
pb.log.debug('Localization: Using the localization key %s is non-performant and should be updated to %s', key, convertedKey);
break;
}
}
//just assign the key. Won't find anything though.
if (util.isNullOrUndefined(convertedKey)) {
convertedKey = key;
}
}
var val = this.g(convertedKey/*, {empty options}*/);
if (val !== null) {
arguments[0] = val;
val = util.format.apply(util, arguments);
}
return val;
};
/**
*
* @method g
* @param {String} key
* @param {Object} [options]
* @param {String} [options.site=global]
* @param {Object} [options.params={}]
* @param {Object} [options.plugin]
* @return {String}
*/
Localization.prototype.g = function(key, options) {
options = options || {
site: pb.SiteService.GLOBAL_SITE,
params: {}
};
//log operation
if (pb.log.isSilly()) {
pb.log.silly('Localization: Localizing key [%s] - Locale [%s]', key, this.language);
}
//error checking
if (!util.isString(key)) {
throw new Error('key parameter is required');
}
if (!util.isObject(options)) {
throw new Error('options parameter must be an object');
}
var params = options.params || {};
if (!util.isObject(params)) {
throw new Error('params parameter is required');
}
//TODO retrieve active plugins for site to narrow down which plugins should be examined during retrieval
//get the current local as object
var locale = this.localeObj;
//get theme to prioritize
var plugin = options.plugin || this.activeTheme;
//define convenience functions
var self = this;
var processValue = function(localization) {
//set cache
self.cache[key] = localization;
//finish processing the value
return localization.isParameterized ?
Localization.replaceParameters(localization.value, params, options.defaultParamVal) :
localization.value;
};
var processKeyBlock = function(keyBlock) {
//check for plugin specific
if (!util.isNullOrUndefined(keyBlock.__plugins)) {
var pluginsBlock = keyBlock.__plugins;
//check for active plugin first
if (!util.isNullOrUndefined(pluginsBlock[plugin])) {
//we found a plugin specific value
return processValue(pluginsBlock[plugin]);
}
//check to see if the other plugins support the key
var pluginsToInspect = Object.keys(pluginsBlock);
for (var j = 0; j < pluginsToInspect.length; j++) {
//skip the active plugin bc we've already checked it
if (plugin === pluginsToInspect[j]) {
continue;
}
//examine the plugin
if (!util.isNullOrUndefined(pluginsBlock[pluginsToInspect[j]])) {
//we found a country & plugin specific value
return processValue(pluginsBlock[pluginsToInspect[j]]);
}
}
}
//no plugin specific key was found. Now check the defaults
if (!util.isNullOrUndefined(keyBlock.__default)) {
return processValue(keyBlock.__default);
}
//couldn't find it in this block
return null;
};
var processLanguageBlock = function(langBlock) {
if (!util.isObject(langBlock)) {
return null;
}
//check for country specific
if (util.isString(locale.countryCode)) {
var countryKey = k(locale.countryCode);
if (!util.isNullOrUndefined(langBlock[countryKey])) {
var countryResult = processKeyBlock(langBlock[countryKey]);
if (util.isString(countryResult)) {
return countryResult;
}
}
}
//we failed to find the value in a country specific block. We need to
//move on to the language
var langResult = processKeyBlock(langBlock);
if (util.isString(langResult)) {
return langResult;
}
//we couldn't find it in this locale
return null;
};
var finalize = function(result) {
return util.isString(result) || options.defaultVal !== undefined ? result : key;
};
//verify that key even exists, if not we're done. Just send back the default val, if provided
if (!Localization.storage[key]) {
return finalize(options.defaultVal);
}
else if (this.cache[key]) {
//we have already processed this key once for this instance
return finalize(processValue(this.cache[key]));
}
//key create key path
var keyBlock = findKeyBlock(key, false);
if (!keyBlock) {
return null;
}
//we found the key. Now we need to dig around and figure out which
//value to pick
var langKey = k(locale.language);
var result = processLanguageBlock(keyBlock[langKey]);
if (!util.isString(result)) {
//check to see if we should fall back to the default locale
var defaultLocale = Localization.parseLocaleStr(Localization.getDefaultLocale());
if (defaultLocale.language !== this.localeObj.language || defaultLocale.countryCode !== this.localeObj.countryCode) {
locale = defaultLocale;
langKey = k(defaultLocale.language);
result = processLanguageBlock(keyBlock[langKey]);
}
else {
result = options.defaultVal;
}
}
//finally, if we have a string result return it otherwise settle on the key
return finalize(result);
};
/**
* Determines the best language to send a user based on the 'accept-language'
* header in the request
*
* @method best
* @param {Request|String} request The request object
* @param {Array} [supported] The array of supported locales
* @return {string} Locale for the request
*/
Localization.best = function(request, supported){
supported = util.isArray(supported) ?
new Locale.Locales(supported) : Localization.supported;
var locales;
var loc = Localization.getDefaultLocale();
if (request) {
var acceptLangStr = util.isString(request) ? request :
(request.headers[Localization.ACCEPT_LANG_HEADER] || loc);
locales = new Locale.Locales(acceptLangStr);
loc = locales.best(supported);
}
return loc;
};
/**
* Initializes the location. Loads all language packs into memory for fast
* retrieval and sets the supported locales for determining what language to
* send the user based on their list of acceptable languages.
*
* @method init
* @param {Function} cb
*/
Localization.init = function(cb) {
Localization.storage = {};
//create path to localization directory
var options = {
recursive: false,
filter: function(filePath) { return filePath.indexOf(JS_EXT) === filePath.length - JS_EXT.length; }
};
var localizationDir = path.join(pb.config.docRoot, 'public', 'localization');
util.getFiles(localizationDir, options, function(err, files) {
if (util.isError(err)) {
return cb(err);
}
var compoundedResult = true;
files.forEach(function(file) {
//parse the file
var obj = null;
try {
obj = require(file);
}
catch(e) {
pb.log.warn('Localization: Failed to load core localization file [%s]. %s', file, e.stack);
//we failed so skip this file
return;
}
//convert file name to locale
var localeObj = Localization.parseLocaleStr(file);
//register the localization as defaults (call private method)
compoundedResult = compoundedResult && Localization._registerLocale(localeObj, obj);
});
//set the supported locales
pb.log.debug("Localization: Supporting - " + JSON.stringify(Object.keys(Localization.supportedLookup)));
cb(null, compoundedResult);
});
};
/**
* Determines if there have been keys registered for the specified locale.
* An example locale string would be: en-US. Where the characters to the
* left of the dash are the language code and the characters to the right
* of the dash represent the country code.
* @static
* @method isSupported
* @param {String} locale
* @return {Boolean}
*/
Localization.isSupported = function(locale) {
if (!util.isString(locale) || locale.length === 0) {
return false;
}
//make sure the locale is properly formatted
var localeObj = Localization.parseLocaleStr(locale);
locale = Localization.formatLocale(localeObj.language, localeObj.countryCode);
return !!Localization.supportedLookup[locale];
};
/**
* Retrieves the localization package for the specified locale
* @static
* @method getLocalizationPackage
* @param {String} locale
* @param {Object} [options] See options for Localization.g
* @return {Object}
*/
Localization.getLocalizationPackage = function(locale, options) {
if (!pb.validation.isNonEmptyStr(locale, true)) {
return null;
}
var ls = new Localization(locale);
var packageObj = {};
Object.keys(Localization.storage).forEach(function(key) {
var result = ls.g(key, options);
var parts = key.split(Localization.KEY_SEP);
if (parts.length === 1) {
packageObj[key] = result;
return;
}
var block = packageObj;
for (var i = 0; i < parts.length; i++) {
if (i === parts.length - 1) {
block[parts[i]] = result;
break;
}
else if (util.isNullOrUndefined(block[parts[i]])) {
block[parts[i]] = {};
}
block = block[parts[i]];
}
});
return packageObj;
};
/**
* @deprecated since 0.5.0
* @static
* @method registerLocalizations
* @param {String} locale
* @param {Object} localizations
* @param {object} options
* @param {string} [options.plugin]
* @return {Boolean}
*/
Localization.registerLocalizations = function(locale, localizations, options) {
pb.log.warn('Localization: Localization.registerLocalizations is deprecated. Use Localization.registerLocale');
return Localization.registerLocale(locale, localizations, options);
};
/**
* Registers a localization package for the provided locale and plugin.
* @private
* @static
* @method _registerLocale
* @param {String|Object} locale
* @param {Object} localizations
* @param {Object} [options]
* @param {String} [options.plugin]
* @return {Boolean}
*/
Localization.registerLocale = function(locale, localizations, options) {
assertOptions(options);
return Localization._registerLocale(locale, localizations, options);
};
/**
* Registers a localization package for the provided locale. Optionally,
* the packaged can be scoped to a specific plugin.
* @private
* @static
* @method _registerLocale
* @param {String|Object} locale
* @param {string} [locale.language] Only required when passing locale as an object
* @param {string} [locale.countryCode]
* @param {Object} localizations
* @param {Object} [options]
* @param {string} [options.plugin=SYSTEM]
* @return {Boolean}
*/
Localization._registerLocale = function(locale, localizations, options) {
locale = parseLocale(locale);
if (!util.isObject(localizations)) {
throw new Error('localizations parameter is required');
}
if (!util.isObject(options)) {
options = {};
}
//log it
if (pb.log.isSilly()) {
pb.log.silly('Localization: Registering locale [%s] for plugin [%s]', Localization.formatLocale(locale.language, locale.countryCode), options.plugin || 'SYSTEM');
}
//load up top level keys into the queue
var queue = [];
var processObj = function(prefix, obj) {
util.forEach(obj, function(val, key) {
queue.push({
key: prefix ? prefix + Localization.KEY_SEP + key : key,
val: val
});
});
};
processObj(null, localizations);
var compoundedResult = true;
while(queue.length > 0) {
var item = queue.shift();
if (util.isObject(item.val)) {
processObj(item.key, item.val);
}
else if (util.isString(item.val)){
compoundedResult = compoundedResult && Localization._registerLocalization(locale, item.key, item.val, options);
}
else {
compoundedResult = false;
pb.log.warn('Localization: Locale [%s] key [%s] provided an invalid value: %s', Localization.formatLocale(locale.language, locale.countryCode), item.key, JSON.stringify(item.val));
}
}
//ensure that we add the supported localization
if (compoundedResult && !Localization.isSupported(locale)) {
Localization.supportedLookup[Localization.formatLocale(locale.language, locale.countryCode)] = locale;
Localization.supported = new Locale.Locales(Object.keys(Localization.supportedLookup));
}
return compoundedResult;
};
/**
* Registers a single localization key for the provided locale and plugin.
* @private
* @static
* @method _registerLocalization
* @param {String} locale
* @param {String} key
* @param {String} value
* @param {Object} options
* @param {String} options.plugin
* @return {Boolean}
*/
Localization.registerLocalization = function(locale, key, value, options) {
assertOptions(options);
return Localization._registerLocalization(locale, key, value, options);
};
/**
* Registers a single localization key for the provided locale. Optionally, the localization can be scoped to a single plugin.
* @private
* @static
* @method _registerLocalization
* @param {String|object} locale
* @param {string} [locale.language] Only required when passing locale as an object
* @param {string} [locale.countryCode]
* @param {String} key
* @param {String} value
* @param {Object} [options]
* @param {String} [options.plugin]
* @return {Boolean}
*/
Localization._registerLocalization = function(locale, key, value, options) {
locale = parseLocale(locale);
if (!util.isString(key)) {
throw new Error('key parameter is required');
}
if (!util.isString(value)) {
throw new Error('value parameter is required');
}
//set defaults
if (!util.isObject(options)) {
options = {};
}
//ensure that the key path exists and set a reference to the block that
//represents the key. We are essentially walking the tree to get to
//the key. When a child node does not exist we create it.
var keyBlock = findKeyBlock(key, true);
//ensure that the language block exists
var langKey = k(locale.language);
if (util.isNullOrUndefined(keyBlock[langKey])) {
keyBlock[langKey] = {};
}
var insertionBlock = keyBlock[langKey];
//check to see if we need to move to a country code block
if (util.isString(locale.countryCode)) {
var countryKey = k(locale.countryCode);
if (util.isNullOrUndefined(insertionBlock[countryKey])) {
insertionBlock[countryKey] = {};
}
insertionBlock = insertionBlock[countryKey];
}
//check to see if we are setting a default localization or a plugin specific one
var valueBlock = {
value: value,
isParameterized: Localization.containsParameters(value)
};
if (util.isString(options.plugin)) {
if (util.isNullOrUndefined(insertionBlock.__plugins)) {
insertionBlock.__plugins = {};
}
insertionBlock.__plugins[options.plugin] = valueBlock;
}
else { //we are inserting a system default
insertionBlock.__default = valueBlock;
}
return true;
};
/**
* Removes a locale and all keys associated with it. Optionally, the
* operation can be scoped to a single plugin.
* @static
* @method unregisterLocale
* @param {String|Object} locale
* @param {string} [locale.language] Only required when locale is passed as an object
* @param {string} [locale.countryCode]
* @param {Object} [options]
* @param {String} [options.plugin]
* @return {Boolean}
*/
Localization.unregisterLocale = function(locale, options) {
locale = parseLocale(locale);
//iterate over all of the keys
var keysRemoved = Object.keys(Localization.storage).reduce(function(prev, key) {
return prev + Localization.unregisterLocalization(locale, key, options);
}, 0);
//remove from quick lookup
delete Localization.supportedLookup[Localization.formatLocale(locale.language, locale.countryCode)];
Localization.supported = new Locale.Locales(Object.keys(Localization.supportedLookup));
return keysRemoved > 0;
};
/**
* Unregisters a single key for the given locale. The locale can be just
* the language or the combination of the language and country code.
* Additionally, the operation can be scoped to a single plugin.
* @static
* @method unregisterLocalization
* @param {String|Object} locale
* @param {string} [locale.language] Only required when passing locale as an object
* @param {string} [locale.countryCode]
* @param {String} key
* @param {Object} [options]
* @param {String} [options.plugin]
* @return {Boolean}
*/
Localization.unregisterLocalization = function(locale, key, options) {
locale = parseLocale(locale);
if (!util.isString(key)) {
throw new Error('key parameter is required');
}
if (!util.isObject(options)) {
options = {};
}
//ensure that the key even exists
if (!Localization.storage[key]) {
return false;
}
//walk the tree looking for the key
var keyBlock = findKeyBlock(key, false);
if (!keyBlock) {
return false;
}
var langKey = k(locale.language);
var langBlock = keyBlock[langKey];
if (util.isNullOrUndefined(langBlock)) {
//the language could not be found
return false;
}
//check for country
if (util.isString(locale.countryCode)) {
//the lang block contains a key for the country code
var countryKey = k(locale.countryCode);
if (!util.isNullOrUndefined(langBlock[countryKey])) {
// look to see if a plugin was specified
var countryBlock = langBlock[countryKey];//translate to plugin key
if (util.isString(options.plugin)) {
//the plugin was specified so we should check the country code block for a sub-section for the plugin
if (util.isString(countryBlock[options.plugin])) {
delete countryBlock[options.plugin];
return true;
}
//we were asked to target the plugin only
return false;
}
}
//no plugin so we should fall through to the default block
if (util.isObject(langBlock[countryKey].__default)) {
delete langBlock[countryKey].__default;
return true;
}
return false;
}
//check the plugin at the lang level
if (util.isString(options.plugin) && util.isObject(langBlock.__plugins)) {
if (util.isString(langBlock.__plugins[options.plugin])) {
delete langBlock.__plugins[options.plugin];
return true;
}
//we were asked to target the plugin only
return false;
}
//finally check the default
if (util.isString(langBlock.__default)) {
delete langBlock.__default;
return true;
}
return false;
};
/**
* Retrieves the default locale for the instance. It first inspects the
* Configuration property localization.defaultLocale. As a last resort it
* will fall back to english. The locale is expected to be of the form:
* [language code]_[country code]
* @static
* @method getDefaultLocale
* @return {String} The default locale
*/
Localization.getDefaultLocale = function() {
return config.localization.defaultLocale || 'en-US';
};
/**
* Retrieves the supported locales
* @static
* @method getSupported
* @return {Array}
*/
Localization.getSupported = function() {
return util.clone(Localization.supported);
};
/**
* Determines if a raw localization value contains named parameters
* @static
* @method containsParameters
* @param {String} localizationValue
* @return {Boolean}
*/
Localization.containsParameters = function(localizationValue) {
if (!util.isString(localizationValue)) {
throw new Error('localizationParameter is required');
}
return localizationValue.search(Localization.PARAM_REPLACEMENT_REGEX) >= 0;
};
/**
* Given a raw localization value and a set of parameters the function will
* attempt to replace the named parameters in the raw value with the values
* provided in the params. When a named parameter is found that was not
* provided a value the defaultVal parameter value is used.
* @static
* @method replaceParameters
* @param {String} value
* @param {Object} params
* @param {String} [defaultVal]
* @return {String}
*/
Localization.replaceParameters = function(value, params, defaultVal) {
if (!util.isString(value)) {
throw new Error('value parameter is required');
}
if (!util.isObject(params)) {
throw new Error('params parameter is required');
}
//We went with a homegrown solution here because it is ~4 times faster
//than the regex expression solution:
//http://stackoverflow.com/questions/1408289/how-can-i-do-string-interpolation-in-javascri
var prev = null;
var isOpen = false;
var variable = '';
var val = '';
for (var i = 0; i < value.length; i++) {
if (!isOpen && value[i] === '{' && prev !== '%') {
isOpen = true;
}
else if (isOpen && value[i] === '}') {
val += params[variable] || defaultVal || variable;
isOpen = false;
variable = '';
}
else if (isOpen) {
variable += value[i];
}
else {
val += value[i];
}
prev = value[i];
}
return val;
};
/**
* Retrieves the supported locales as an array where each item in the array
* contains a value (locale) and a name (locale specific representation of
* the locale).
* @static
* @method getSupportedWithDisplay
* @return {Array}
*/
Localization.getSupportedWithDisplay = function() {
var supported = Localization.getSupported();
return supported.map(function(locale) {
var localization = new Localization(locale);
return {
value: locale,
name: localization.g('generic.LOCALE_DISPLAY'/*, {empty options}*/)
};
});
};
/**
* Parses a locale or file path to a locale file and extracts the language
* and country code into an object.
* @static
* @method parseLocaleStr
* @param {String|object} filePath
* @param {string} [filePath.language] Only required when passing filePath as an object
* @param {string} [filePath.countryCode] Only required when passing filePath as an object
* @return {Object}
*/
Localization.parseLocaleStr = function(filePath) {
if (util.isObject(filePath)) {
if (!util.isString(filePath.language)) {
throw new Error('filePath.language parameter is required');
}
if (!util.isNullOrUndefined(filePath.countryCode) && !util.isString(filePath.countryCode)) {
throw new Error('filePath.countryCode parameter must be a string');
}
//we have a valid locale we can stop
return filePath;
}
if (!util.isString(filePath)) {
throw new Error('filePath parameter is required');
}
//detect what file path separator we are using. Unix first then windows
var lastSlashPos = filePath.lastIndexOf('/');
if (lastSlashPos < 0) {
lastSlashPos = filePath.lastIndexOf('\\');
}
var extPos = filePath.lastIndexOf(JS_EXT);
if (extPos < 0) {
extPos = filePath.length;
}
var locale = filePath.substr(lastSlashPos + 1, extPos - lastSlashPos - 1);
var parts = locale.split(Localization.LOCALE_PART_SEP);
var lang = parts[0] ? parts[0].toLowerCase() : null;
var countryCode = parts[1] ? parts[1].toUpperCase() : null;
return {
language: lang,
countryCode: countryCode
};
};
/**
* Formats a language and an optional country code into a proper locale
* format (lang-COUNTRY)
* @static
* @method formatLocale
* @param {String} language
* @param {String} [countryCode]
* @return {String}
*/
Localization.formatLocale = function(language, countryCode) {
if (!util.isString(language)) {
throw new Error('language parameter is required');
}
if (!util.isNullOrUndefined(countryCode) && !util.isString(countryCode)) {
throw new Error('countryCode parameter must be a string');
}
var localeStr = language.toLowerCase();
if (util.isString(countryCode)) {
localeStr += Localization.LOCALE_PART_SEP + countryCode.toUpperCase();
}
return localeStr;
};
/**
* Asserts that the options parameter is provided and that it contains a
* property "plugin" that is a string.
* @private
* @static
* @method assertOptions
* @param {Object} options
* @param {String} options.plugin
*/
function assertOptions(options) {
if (!util.isObject(options)) {
throw new Error('options parameter is required');
}
if (!util.isString(options.plugin)) {
throw new Error('options.plugin is required');
}
}
/**
* Takes a locale object or string representation. When a string it is
* parsed to an object. When an object is passed it is verified. The
* function throws an error when it finds invalid format.
* @private
* @static
* @method parseLocale
* @param {String|Object} locale
* @param {string} [locale.language] Only required when passing an object
* @return {Object}
*/
function parseLocale(locale) {
if (util.isString(locale)) {
locale = Localization.parseLocaleStr(locale);
}
if (util.isObject(locale)) {
if (!util.isString(locale.language)) {
throw new Error('locale.language is required');
}
}
else {
throw new Error('locale is required');
}
return locale;
}
/**
* Formats a given key to be formatted as a "private" property in the
* storage structure. This is to prevent collisions between localization
* keys.
* @private
* @static
* @method k
* @param {String} key
* @return {String}
*/
function k(key) {
return '__' + key;
}
/**
* Navigates the storage structure to find where a localization key's
* values live
* @private
* @static
* @method findKeyBlock
* @param {String} key
* @param {boolean} create
* @return {Object} The object that contains the values for the key
*/
function findKeyBlock(key, create) {
if (create && typeof Localization.storage[key] === 'undefined') {
Localization.storage[key] = {};
}
return Localization.storage[key];
}
return Localization;
};
