Source: ui/localization.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  8. goog.provide('shaka.ui.Localization');
  9. goog.provide('shaka.ui.Localization.ConflictResolution');
  11. goog.require('shaka.util.FakeEvent');
  12. goog.require('shaka.util.FakeEventTarget');
  13. goog.require('shaka.util.Iterables');
  14. goog.require('shaka.util.LanguageUtils');
  17. // TODO: link to the design and usage documentation here
  18. // b/117679670
  19. /**
  20.  * Localization system provided by the shaka ui library.
  21.  * It can be used to store the various localized forms of
  22.  * strings that are expected to be displayed to the user.
  23.  * If a string is not available, it will return the localized
  24.  * form in the closest related locale.
  25.  *
  26.  * @final
  27.  * @export
  28.  */
  29. shaka.ui.Localization = class extends shaka.util.FakeEventTarget {
  30.   /**
  31.    * @param {string} fallbackLocale
  32.    *    The fallback locale that should be used. It will be assumed that this
  33.    *    locale should have entries for just about every request.
  34.    */
  35.   constructor(fallbackLocale) {
  36.     super();
  38.     /** @private {string} */
  39.     this.fallbackLocale_ = shaka.util.LanguageUtils.normalize(fallbackLocale);
  41.     /**
  42.      * The current mappings that will be used when requests are made. Since
  43.      * nothing has been loaded yet, there will be nothing in this map.
  44.      *
  45.      * @private {!Map.<string, string>}
  46.      */
  47.     this.currentMap_ = new Map();
  49.     /**
  50.      * The locales that were used when creating |currentMap_|. Since we don't
  51.      * have anything when we first initialize, an empty set means "no
  52.      * preference".
  53.      *
  54.      * @private {!Set.<string>}
  55.      */
  56.     this.currentLocales_ = new Set();
  58.     /**
  59.      * A map of maps where:
  60.      *  - The outer map is a mapping from locale code to localizations.
  61.      *  - The inner map is a mapping from id to localized text.
  62.      *
  63.      * @private {!Map.<string, !Map.<string, string>>}
  64.      */
  65.     this.localizations_ = new Map();
  66.   }
  68.   /**
  69.    * @override
  70.    * @export
  71.    */
  72.   release() {
  73.     // Placeholder so that readers know this implements IReleasable (via
  74.     // FakeEventTarget)
  75.     super.release();
  76.   }
  78.   /**
  79.    * Request the localization system to change which locale it serves. If any of
  80.    * of the preferred locales cannot be found, the localization system will fire
  81.    * an event identifying which locales it does not know. The localization
  82.    * system will then continue to operate using the closest matches it has.
  83.    *
  84.    * @param {!Iterable.<string>} locales
  85.    *    The locale codes for the requested locales in order of preference.
  86.    * @export
  87.    */
  88.   changeLocale(locales) {
  89.     const Class = shaka.ui.Localization;
  91.     // Normalize the locale so that matching will be easier. We need to reset
  92.     // our internal set of locales so that we have the same order as the new
  93.     // set.
  94.     this.currentLocales_.clear();
  95.     for (const locale of locales) {
  96.       this.currentLocales_.add(shaka.util.LanguageUtils.normalize(locale));
  97.     }
  99.     this.updateCurrentMap_();
  101.     // Check if we have support for the exact locale requested. Even through we
  102.     // will do our best to return the most relevant results, we need to tell
  103.     // app that some data may be missing.
  104.     const missing = shaka.util.Iterables.filter(
  105.         this.currentLocales_,
  106.         (locale) => !this.localizations_.has(locale));
  108.     if (missing.length) {
  109.       this.dispatchEvent(new shaka.util.FakeEvent(
  110.           Class.UNKNOWN_LOCALES,
  111.           (new Map()).set('locales', missing)));
  112.     }
  114.     const found = shaka.util.Iterables.filter(
  115.         this.currentLocales_,
  116.         (locale) => this.localizations_.has(locale));
  118.     const data = (new Map()).set(
  119.         'locales', found.length ? found : [this.fallbackLocale_]);
  120.     this.dispatchEvent(new shaka.util.FakeEvent(
  121.         Class.LOCALE_CHANGED,
  122.         data));
  123.   }
  125.   /**
  126.    * Insert a set of localizations for a single locale. This will amend the
  127.    * existing localizations for the given locale.
  128.    *
  129.    * @param {string} locale
  130.    *   The locale that the localizations should be added to.
  131.    * @param {!Map.<string, string>} localizations
  132.    *   A mapping of id to localized text that should used to modify the internal
  133.    *   collection of localizations.
  134.    * @param {shaka.ui.Localization.ConflictResolution=} conflictResolution
  135.    *   The strategy used to resolve conflicts when the id of an existing entry
  136.    *   matches the id of a new entry. Default to |USE_NEW|, where the new
  137.    *   entry will replace the old entry.
  138.    * @return {!shaka.ui.Localization}
  139.    *   Returns |this| so that calls can be chained.
  140.    * @export
  141.    */
  142.   insert(locale, localizations, conflictResolution) {
  143.     const Class = shaka.ui.Localization;
  144.     const ConflictResolution = shaka.ui.Localization.ConflictResolution;
  145.     const FakeEvent = shaka.util.FakeEvent;
  147.     // Normalize the locale so that matching will be easier.
  148.     locale = shaka.util.LanguageUtils.normalize(locale);
  150.     // Default |conflictResolution| to |USE_NEW| if it was not given. Doing it
  151.     // here because it would create too long of a parameter list.
  152.     if (conflictResolution === undefined) {
  153.       conflictResolution = ConflictResolution.USE_NEW;
  154.     }
  156.     // Make sure we have an entry for the locale because we are about to
  157.     // write to it.
  158.     const table = this.localizations_.get(locale) || new Map();
  159.     localizations.forEach((value, id) => {
  160.       // Set the value if we don't have an old value or if we are to replace
  161.       // the old value with the new value.
  162.       if (!table.has(id) || conflictResolution == ConflictResolution.USE_NEW) {
  163.         table.set(id, value);
  164.       }
  165.     });
  166.     this.localizations_.set(locale, table);
  168.     // The data we use to make our map may have changed, update the map we pull
  169.     // data from.
  170.     this.updateCurrentMap_();
  172.     this.dispatchEvent(new FakeEvent(Class.LOCALE_UPDATED));
  174.     return this;
  175.   }
  177.   /**
  178.    * Set the value under each key in |dictionary| to the resolved value.
  179.    * Convenient for apps with some kind of data binding system.
  180.    *
  181.    * Equivalent to:
  182.    *    for (const key of dictionary.keys()) {
  183.    *      dictionary.set(key, localization.resolve(key));
  184.    *    }
  185.    *
  186.    * @param {!Map.<string, string>} dictionary
  187.    * @export
  188.    */
  189.   resolveDictionary(dictionary) {
  190.     for (const key of dictionary.keys()) {
  191.       // Since we are not changing what keys are in the map, it is safe to
  192.       // update the map while iterating it.
  193.       dictionary.set(key, this.resolve(key));
  194.     }
  195.   }
  197.   /**
  198.    * Request the localized string under the given id. If there is no localized
  199.    * version of the string, then the fallback localization will be given
  200.    * ("en" version). If there is no fallback localization, a non-null empty
  201.    * string will be returned.
  202.    *
  203.    * @param {string} id The id for the localization entry.
  204.    * @return {string}
  205.    * @export
  206.    */
  207.   resolve(id) {
  208.     const Class = shaka.ui.Localization;
  209.     const FakeEvent = shaka.util.FakeEvent;
  211.     /** @type {string} */
  212.     const result = this.currentMap_.get(id);
  214.     // If we have a result, it means that it was found in either the current
  215.     // locale or one of the fall-backs.
  216.     if (result) {
  217.       return result;
  218.     }
  220.     // Since we could not find the result, it means it is missing from a large
  221.     // number of locales. Since we don't know which ones we actually checked,
  222.     // just tell them the preferred locale.
  224.     const data = new Map()
  225.         // Make a copy to avoid leaking references.
  226.         .set('locales', Array.from(this.currentLocales_))
  227.         .set('missing', id);
  228.     this.dispatchEvent(new FakeEvent(Class.UNKNOWN_LOCALIZATION, data));
  230.     return '';
  231.   }
  233.   /**
  234.    * The locales currently used. An empty set means "no preference".
  235.    *
  236.    * @return {!Set.<string>}
  237.    * @export
  238.    */
  239.   getCurrentLocales() {
  240.     return this.currentLocales_;
  241.   }
  243.   /**
  244.    * @private
  245.    */
  246.   updateCurrentMap_() {
  247.     const LanguageUtils = shaka.util.LanguageUtils;
  249.     /** @type {!Map.<string, !Map.<string, string>>} */
  250.     const localizations = this.localizations_;
  251.     /** @type {string} */
  252.     const fallbackLocale = this.fallbackLocale_;
  253.     /** @type {!Iterable.<string>} */
  254.     const preferredLocales = this.currentLocales_;
  256.     /**
  257.      * We want to create a single map that gives us the best possible responses
  258.      * for the current locale. To do this, we will go through be loosest
  259.      * matching locales to the best matching locales. By the time we finish
  260.      * flattening the maps, the best result will be left under each key.
  261.      *
  262.      * Get the locales we should use in order of preference. For example with
  263.      * preferred locales of "elvish-WOODLAND" and "dwarfish-MOUNTAIN" and a
  264.      * fallback of "common-HUMAN", this would look like:
  265.      *
  266.      * new Set([
  267.      *    // Preference 1
  268.      *    'elvish-WOODLAND',
  269.      *    // Preference 1 Base
  270.      *    'elvish',
  271.      *    // Preference 1 Siblings
  272.      *    'elvish-WOODLAND', 'elvish-WESTWOOD', 'elvish-MARSH,
  273.      *    // Preference 2
  274.      *    'dwarfish-MOUNTAIN',
  275.      *    // Preference 2 base
  276.      *    'dwarfish',
  277.      *    // Preference 2 Siblings
  278.      *    'dwarfish-MOUNTAIN', 'dwarfish-NORTH', "dwarish-SOUTH",
  279.      *    // Fallback
  280.      *    'common-HUMAN',
  281.      * ])
  282.      *
  283.      * @type {!Set.<string>}
  284.      */
  285.     const localeOrder = new Set();
  287.     for (const locale of preferredLocales) {
  288.       localeOrder.add(locale);
  289.       localeOrder.add(LanguageUtils.getBase(locale));
  291.       const siblings = shaka.util.Iterables.filter(
  292.           localizations.keys(),
  293.           (other) => LanguageUtils.areSiblings(other, locale));
  295.       // Sort the siblings so that they will always appear in the same order
  296.       // regardless of the order of |localizations|.
  297.       siblings.sort();
  298.       for (const locale of siblings) {
  299.         localeOrder.add(locale);
  300.       }
  302.       const children = shaka.util.Iterables.filter(
  303.           localizations.keys(),
  304.           (other) => LanguageUtils.getBase(other) == locale);
  306.       // Sort the children so that they will always appear in the same order
  307.       // regardless of the order of |localizations|.
  308.       children.sort();
  309.       for (const locale of children) {
  310.         localeOrder.add(locale);
  311.       }
  312.     }
  314.     // Finally we add our fallback (something that should have all expected
  315.     // entries).
  316.     localeOrder.add(fallbackLocale);
  318.     // Add all the sibling maps.
  319.     /** @type {!Array.<!Map.<string, string>>} */
  320.     const mergeOrder = [];
  321.     for (const locale of localeOrder) {
  322.       const map = localizations.get(locale);
  323.       if (map) {
  324.         mergeOrder.push(map);
  325.       }
  326.     }
  328.     // We need to reverse the merge order. We build the order based on most
  329.     // preferred to least preferred. However, the merge will work in the
  330.     // opposite order so we must reverse our maps so that the most preferred
  331.     // options will be applied last.
  332.     mergeOrder.reverse();
  334.     // Merge all the options into our current map.
  335.     this.currentMap_.clear();
  336.     for (const map of mergeOrder) {
  337.       map.forEach((value, key) => {
  338.         this.currentMap_.set(key, value);
  339.       });
  340.     }
  342.     // Go through every key we have and see if any preferred locales are
  343.     // missing entries. This will allow app developers to find holes in their
  344.     // localizations.
  346.     /** @type {!Iterable.<string>} */
  347.     const allKeys = this.currentMap_.keys();
  349.     /** @type {!Set.<string>} */
  350.     const missing = new Set();
  352.     for (const locale of this.currentLocales_) {
  353.       // Make sure we have a non-null map. The diff will be easier that way.
  354.       const map = this.localizations_.get(locale) || new Map();
  355.       shaka.ui.Localization.findMissingKeys_(map, allKeys, missing);
  356.     }
  358.     if (missing.size > 0) {
  359.       const data = new Map()
  360.           // Make a copy of the preferred locales to avoid leaking references.
  361.           .set('locales', Array.from(preferredLocales))
  362.           // Because more people like arrays more than sets, convert the set to
  363.           // an array.
  364.           .set('missing', Array.from(missing));
  366.       this.dispatchEvent(new shaka.util.FakeEvent(
  367.           shaka.ui.Localization.MISSING_LOCALIZATIONS,
  368.           data));
  369.     }
  370.   }
  372.   /**
  373.    * Go through a map and add all the keys that are in |keys| but not in
  374.    * |map| to |missing|.
  375.    *
  376.    * @param {!Map.<string, string>} map
  377.    * @param {!Iterable.<string>} keys
  378.    * @param {!Set.<string>} missing
  379.    * @private
  380.    */
  381.   static findMissingKeys_(map, keys, missing) {
  382.     for (const key of keys) {
  383.       // Check if the value is missing so that we are sure that it does not
  384.       // have a value. We get the value and not just |has| so that a null or
  385.       // empty string will fail this check.
  386.       if (!map.get(key)) {
  387.         missing.add(key);
  388.       }
  389.     }
  390.   }
  391. };
  394. /**
  395.  * An enum for how the localization system should resolve conflicts between old
  396.  * translations and new translations.
  397.  *
  398.  * @enum {number}
  399.  * @export
  400.  */
  401. shaka.ui.Localization.ConflictResolution = {
  402.   'USE_OLD': 0,
  403.   'USE_NEW': 1,
  404. };
  406. /**
  407.  * The event name for when locales were requested, but we could not find any
  408.  * entries for them. The localization system will continue to use the closest
  409.  * matches it has.
  410.  *
  411.  * @const {string}
  412.  * @export
  413.  */
  414. shaka.ui.Localization.UNKNOWN_LOCALES = 'unknown-locales';
  416. /**
  417.  * The event name for when an entry could not be found in the preferred locale,
  418.  * related locales, or the fallback locale.
  419.  *
  420.  * @const {string}
  421.  * @export
  422.  */
  423. shaka.ui.Localization.UNKNOWN_LOCALIZATION = 'unknown-localization';
  425. /**
  426.  * The event name for when entries are missing from the user's preferred
  427.  * locale, but we were able to find an entry in a related locale or the fallback
  428.  * locale.
  429.  *
  430.  * @const {string}
  431.  * @export
  432.  */
  433. shaka.ui.Localization.MISSING_LOCALIZATIONS = 'missing-localizations';
  435. /**
  436.  * The event name for when a new locale has been requested and any previously
  437.  * resolved values should be updated.
  438.  *
  439.  * @const {string}
  440.  * @export
  441.  */
  442. shaka.ui.Localization.LOCALE_CHANGED = 'locale-changed';
  444. /**
  445.  * The event name for when |insert| was called and it changed entries that could
  446.  * affect previously resolved values.
  447.  *
  448.  * @const {string}
  449.  * @export
  450.  */
  451. shaka.ui.Localization.LOCALE_UPDATED = 'locale-updated';
  453. /**
  454.  * @event shaka.ui.Localization.UnknownLocalesEvent
  455.  * @property {string} type
  456.  *   'unknown-locales'
  457.  * @property {!Array.<string>} locales
  458.  *    The locales that the user wanted but could not be found.
  459.  * @exportDoc
  460.  */
  462. /**
  463.  * @event shaka.ui.Localization.MissingLocalizationsEvent
  464.  * @property {string} type
  465.  *   'unknown-localization'
  466.  * @property {!Array.<string>} locales
  467.  *    The locales that the user wanted.
  468.  * @property {string} missing
  469.  *    The id of the unknown entry.
  470.  * @exportDoc
  471.  */
  473. /**
  474.  * @event shaka.ui.Localization.MissingLocalizationsEvent
  475.  * @property {string} type
  476.  *   'missing-localizations'
  477.  * @property {string} locale
  478.  *    The locale that the user wanted.
  479.  * @property {!Array.<string>} missing
  480.  *    The ids of the missing entries.
  481.  * @exportDoc
  482.  */
  484. /**
  485.  * @event shaka.ui.Localization.LocaleChangedEvent
  486.  * @property {string} type
  487.  *   'locale-changed'
  488.  * @property {!Array.<string>} locales
  489.  *    The new set of locales that user wanted,
  490.  *    and that were successfully found.
  491.  * @exportDoc
  492.  */