cloudux-l10n
Version:
Package for providing localization to avid static plugins
129 lines (122 loc) • 4.42 kB
JavaScript
/*
* Copyright 2016, 2020, 2022 by Avid Technology, Inc.
*/
/**
* @module avid-mcux-l10n
* @description MediaCentral|UX Localization
* ## API description
*
* To be able to use this API you have to provide the localization files at your
* project. This is name convention in the name of this files that resolves
* by API. To be able to obtain the file according to the current runtime
* localization you should require ```some-file-name.l10n.json``` file where
* In case if German is being active locale, file name request will be resolved
* to `some-string.de.json` at runtime level to the name of the current locale.
* Localization has names according to [ISO_639-1](https://en.wikipedia.org/wiki/ISO_639-1)
*
* #### Supported languages
*
* Currenly suppported languages are
* ```
* fr de ja zh es ko it ar tr
* ```
* #### Example of the file system structure
*```
* static-plugin-folder/
* ├── src
* │ ├── index.js
* │ ├── l10n
* │ │ ├── lang.de.json
* │ │ ├── lang.fr.json
* │ │ └── lang.en.json
* │ └── views
* │ ├── settings-view
* │ │ ├── index.js
* ```
* #### Localization file structure
*
* Localization file has the flat json object structure. Nesting object is
* currently unsupported. Example of the ``lang.en.json``:
* ```
* {
* 'hello-msg': 'Hallo World'
* }
* ```
* the same file in different language will have the same key6 but localized
* value. For instance, in Deutch ``lang.de.json`` will be
* ```
* {
* 'hello-msg': 'Hallo Welt'
* }
* ```
* #### Require the localization file
*
* In the above example we placed the three localization files in the folder
* named ```l10n```. This localization should be required as an external module.
* For instance, by using AMD module pattern
* Or, if you are using the webpack, you have to add the path to
* localization file as an external dependency. See example below.
*
*
* @example
* //@file "static-plugin-folder/src/views/settings-view/index.js";
* const l10nData = require('../../l10n/lang.l10n.json'); // path relative to this file
* // If current locale is === "de" will be required file named lang.de.json
* // l10nData = { 'submit': 'Einreichen' };
* const localize = l10n.getLocalization(l10nData);
*
*/
/**
* Replace the template {number} to appropriate argument position
* @name module:avid-mcux-l10n~formatString
* @function
* @param {String} str - template string in format {number}
* @param {String} [templateValues] - parameters to be placed to template
* @return {String} - localized string
* into the template
*/
function formatString(str, ...templateValues) {
return str.replace(/\{(\d{1,3})\}/g, (a, i) => templateValues[i]);
}
/**
* Get the localization function for the given localization data that
* was provided by API.
* This will return a localization function that contains returns localization
* for the key value pairs.
* The constructor does a synchronous load, so it will block while
* @example
*
* const localize = l10n.getLocalization({ 'submit': 'Einreichen' });
*
* @param {Object} data - the localized data to get the localization for
* @return {module:avid-mcux-l10n~localize} function that localize key value pairs
*/
export function getLocalization(data) {
/**
* Get localized value for the key. Supports templating
* @function
* @example
*
* const localize = getLocalization({
* 'submit': 'Einreichen {0}',
* 'first': 'zuerst'
* });
* const first = localize('first');
* localize('submit', first);// === 'Einreichen zuerst'
*
* @name module:avid-mcux-l10n~localize
* @param {String} key - string value key to be localized
* @param {String} [templateValues] - parameters to be placed to template
* @retrun {String} - localized string
*/
function localize(key, ...templateValues) {
const localizedString = data[key];
if (localizedString === undefined) {
return key;
}
return templateValues.length
? formatString(localizedString, ...templateValues)
: localizedString;
}
return localize;
}