/*
* Your installation or use of this SugarCRM file is subject to the applicable
* terms available at
* http://support.sugarcrm.com/Resources/Master_Subscription_Agreements/.
* If you do not agree to all of the applicable terms or do not have the
* authority to bind the entity as an authorized representative, then do not
* install or use this SugarCRM file.
*
* Copyright (C) SugarCRM Inc. All rights reserved.
*/
const Template = require('../view/template');
const User = require('./user');
/**
* Language Helper.
*
* Provides convenient functions to pull language strings out of a
* language label cache.
*
* @module Core/Language
*/
/**
* Retrieves a string of a given type.
*
* If the label is a template, it will be compiled and executed with the
* given `context`.
*
* @param {string} type Type of string pack: `app_strings`,
* `app_list_strings` or `mod_strings`.
* @param {string} key Key of the string to retrieve.
* @param {string} [module] Module the label belongs to.
* @param {string|boolean|number|Array|Object} [context] Template context.
* @return {string|undefined} String for the given key.
* @private
*/
function get(type, key, module, context) {
var str,
bundle = SUGAR.App.metadata.getStrings(type);
bundle = module ? bundle[module] : bundle;
if (!bundle || !_.isString(bundle[key])) {
return;
}
str = sanitize(bundle[key]);
if (!_.isUndefined(context) && (str.indexOf('{{') > -1)) {
key = 'lang.' + (module ? key + '.' + module : key);
var tpl = Handlebars.templates[key];
str = tpl ? tpl(context) : Template.compile(key, str)(context);
}
return str;
};
/**
* Sanitizes (strips a trailing colon from) a string.
*
* @param {string} str String to sanitize.
* @return {string} Sanitized string or `str` parameter if it's not a
* string.
* @private
*/
function sanitize(str) {
return (str.slice(-1) === ':') ? str.slice(0, -1) : str;
};
/**
* The default language defined by
* {@link #setDefaultLanguage}. Use {@link #getDefaultLanguage} to
* retrieve this setting.
*
* @property {string} defaultLanguage
* @private
*/
let defaultLanguage;
/**
* The language that is loaded by the app and defined by
* {@link #setCurrentLanguage}. Use {@link #getLanguage} to retrieve
* this setting.
*
* @property {string} currentLanguage
* @private
*/
let currentLanguage;
/**
* @alias module:Core/Language
*/
module.exports = {
/**
* The display direction for the current language.
*
* @type {string}
*/
direction: 'ltr',
/**
* Retrieves a string for a given key.
*
* This function searches the module strings first and falls back to the
* app strings.
*
* If the label is a template, it will be compiled and executed with the
* given `context`.
*
* @param {string} key Key of the string to retrieve.
* @param {string|Array} [module] Module the label belongs to. If an
* array is passed, it will look through each module by the given
* order, returning the first string whose key is found in the
* module's language strings.
* @param {string|boolean|number|Array|Object} [context] The template
* context to pass to the template in order to populate template variables.
* @return {string} String for the given key or the `key` parameter if
* the key is not found in language pack.
*/
get: function(key, module, context) {
var str = this.getModString(key, module, context) ||
this.getAppString(key, context) ||
key;
return str;
},
/**
* Searches the module strings for a given key.
*
* @param {string} key Key of the string to retrieve.
* @param {string|Array} [module] Module the label belongs to. If an
* array is passed, it will look through each module by the given
* order, returning the first string whose key is found in the
* module's language strings.
* @param {string|boolean|number|Array|Object} [context] The template
* context to pass to the template in order to populate template variables.
* @return {string|undefined} String for the given key from the module
* language strings. `undefined` if not found.
*/
getModString: function(key, module, context) {
var moduleString;
if (_.isArray(module)) {
_.find(module, function(moduleName) {
moduleString = get('mod_strings', key, moduleName, context);
return !_.isEmpty(moduleString);
}, this);
} else {
moduleString = get('mod_strings', key, module, context);
}
return moduleString;
},
/**
* Retrieves an application string for a given key.
*
* @param {string} key Key of the string to retrieve.
* @param {string|boolean|number|Array|Object} [context] The template
* context to pass to the string/template in order to populate template
* variables.
* @return {string|undefined} String for the given key from language
* strings. `undefined` if not found.
*/
getAppString: function(key, context) {
return get('app_strings', key, null, context);
},
/**
* Retrieves an application list string or object.
*
* @param {string} key Key of the string to retrieve.
* @return {string|Object} String or object for the given key. If key
* is not found, an empty object is returned.
*/
getAppListStrings: function(key) {
var list = SUGAR.App.metadata.getStrings('app_list_strings')[key] || {};
if (_.isArray(list)) {
var obj = {};
_.each(list, function(tuple) {
if (_.isString(tuple)) {
obj[tuple] = tuple;
} else if (_.isArray(tuple) && tuple.length === 2) {
obj[tuple[0]] = tuple[1];
}
});
list = obj;
}
return list;
},
/**
* Gets the translated module name (by default, in singular form).
*
* Falls back to the plural form if the singular form is not found, and
* eventually falls back to the `module` passed in.
*
* @param {string} module The module.
* @param {Object} [options] Options object for `getModuleName`.
* @param {boolean} [options.plural] Returns the plural form if `true`,
* singular otherwise.
* @param {string} [options.defaultValue] Value to be returned if the
* module language string is not found.
* @return {string} The module name.
*/
getModuleName: function(module, options) {
options = options || {};
var name = !options.plural &&
this.getModString('LBL_MODULE_NAME_SINGULAR', module) ||
this.getModString('LBL_MODULE_NAME', module);
if (!name && !_.isUndefined(options.defaultValue)) {
name = this.get(options.defaultValue);
}
return name || module;
},
/**
* Returns the correct ordered array of strings for a given list.
*
* @param {string} listName Name of the strings array to retrieve.
* @return {Array} The array of strings.
*/
getAppListKeys: function(listName) {
var keys = [],
list = SUGAR.App.metadata.getStrings('app_list_strings')[listName] || {};
if (_.isArray(list)) {
_.each(list, function(tuple) {
if (tuple.length === 2) {
keys.push(tuple[0]);
}
});
} else if (_.isObject(list)) {
keys = _.keys(list);
}
return keys;
},
/**
* Gets the IETF's BCP 47 language code for the current app language.
*
* @return {string} The IETF's BCP 47 language code of the default language.
* (e.g. `en_us`, `pt_PT`). Note: We use `_` instead of `-`.
*/
getLanguage: function() {
return currentLanguage;
},
/**
* Sets app language code and syncs it with the server.
*
* @param {string} language language code such as `en_us`.
* @param {Function} [callback] Callback function to be called on
* language set completes.
* @param {Object} [options] Extra options.
* @param {boolean} [options.noSync=false] `true` if you don't need to
* fetch /metadata.
* @param {boolean} [options.noUserUpdate=false] `true` if you don't need
* to update /me.
*/
setLanguage: function(language, callback, options) {
var self = this;
options = options || {};
_.each(Handlebars.templates, function(value, key) {
if (key.indexOf('lang.') === 0) {
delete Handlebars.templates[key];
}
});
if (options.noSync === true) {
this.updateLanguage(language);
return;
}
SUGAR.App.sync({
callback: function(err) {
var langHasChanged = false;
if (!err) {
self.updateLanguage(language);
langHasChanged = !SUGAR.App.api.isAuthenticated() && !options.noUserUpdate;
SUGAR.App.cache.set('langHasChanged', langHasChanged);//persist even after reloads
}
if (callback) callback(err);
},
getPublic: !SUGAR.App.api.isAuthenticated(),
noUserUpdate: options.noUserUpdate || false,
language: language,
forceRefresh: true, // Needed to make sure new labels are injected
metadataTypes: ['labels']
});
},
/**
* Updates language code and the display direction.
*
* @param {string} language Language code as defined in Sugar.
* (e.g. `en_us`, `pt_PT`)
*/
updateLanguage: function(language) {
SUGAR.App.cache.set('lang', language);
User.setPreference('language', language);
this.setCurrentLanguage(language);
SUGAR.App.trigger('app:locale:change', language);
// Add the current language for improved screen reader accessibility
if (document && document.documentElement) {
var currentLanguageForDom = _.first(language.split('_'));
// Use the simple language code as per HTML qualifications
document.documentElement.lang = currentLanguageForDom;
}
},
/**
* Sets the app default language to the language specified. Use
* {@link #getDefaultLanguage} to get the current language.
*
* @param {string} language The IETF's BCP 47 language code to set the
* default language to. (e.g. `en_us`, `pt_PT`).
* Note: We use `_` instead of `-`.
*/
setDefaultLanguage: function(language) {
defaultLanguage = language;
},
/**
* Gets the default language set in the system.
*
* @return {string} The IETF's BCP 47 language code of the default language.
* (e.g. `en_us`, `pt_PT`). Note: We use `_` instead of `-`.
*/
getDefaultLanguage: function() {
return defaultLanguage;
},
/**
* Sets the current language to the language specified. Use
* {@link #getLanguage} to get the current language.
*
* Calls {@link #setDirection} with the new language code.
*
* @param {string} language The language to set the current language to.
*/
setCurrentLanguage: function(language) {
currentLanguage = language;
this.setDirection(language);
},
/**
* Sets the {@link #direction} to the desired direction according to
* the language code specified.
*
* @fires 'lang:direction:change' if the language direction has
* changed.
*
* @param {string} lang Language code that the direction is based on.
*/
setDirection: function(lang) {
//FIXME: SC-3358 Should be getting the RTL languages from metadata.
var rtlLanguages = ['he_IL', 'ar_SA'],
isRTL = _.contains(rtlLanguages, lang),
prevDirection = this.direction;
this.direction = isRTL ? 'rtl' : 'ltr';
if (this.direction !== prevDirection) {
SUGAR.App.trigger('lang:direction:change');
}
},
_get: function(type, key, module, context) {
if (!SUGAR.App.config.sidecarCompatMode) {
SUGAR.App.logger.error('Core.Language#_get is a private method that you are not allowed ' +
'to access. Please use only the public API.');
return;
}
SUGAR.App.logger.warn('Core.Language#_get is a private method that you should not access to. ' +
'You will NOT be allowed to access it in the next release. Please update your code to rely on the public ' +
'API only.');
return get(type, key, module, context);
},
_sanitize: function(str) {
if (!SUGAR.App.config.sidecarCompatMode) {
SUGAR.App.logger.error('Core.Language#_sanitize is a private method that you are not allowed ' +
'to access. Please use only the public API.');
return;
}
SUGAR.App.logger.warn('Core.Language#_sanitize is a private method that you should not access. ' +
'You will NOT be allowed to access it in the next release. Please update your code to rely on the public ' +
'API only.');
return sanitize(str);
}
};