Source: ui/localization.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  19. goog.provide('shaka.ui.Localization');
  20. goog.provide('shaka.ui.Localization.ConflictResolution');
  22. goog.require('shaka.util.FakeEvent');
  23. goog.require('shaka.util.FakeEventTarget');
  24. goog.require('shaka.util.Iterables');
  25. goog.require('shaka.util.LanguageUtils');
  28. // TODO: link to the design and usage documentation here
  29. // b/117679670
  30. /**
  31.  * Localization system provided by the shaka ui library.
  32.  * It can be used to store the various localized forms of
  33.  * strings that are expected to be displayed to the user.
  34.  * If a string is not available, it will return the localized
  35.  * form in the closest related locale.
  36.  *
  37.  * @implements {EventTarget}
  38.  * @final
  39.  * @export
  40.  */
  41. shaka.ui.Localization = class {
  42.   /**
  43.    * @param {string} fallbackLocale
  44.    *    The fallback locale that should be used. It will be assumed that this
  45.    *    locale should have entries for just about every request.
  46.    */
  47.   constructor(fallbackLocale) {
  48.     /** @private {string} */
  49.     this.fallbackLocale_ = shaka.util.LanguageUtils.normalize(fallbackLocale);
  51.     /**
  52.      * The current mappings that will be used when requests are made. Since
  53.      * nothing has been loaded yet, there will be nothing in this map.
  54.      *
  55.      * @private {!Map.<string, string>}
  56.      */
  57.     this.currentMap_ = new Map();
  59.     /**
  60.      * The locales that were used when creating |currentMap_|. Since we don't
  61.      * have anything when we first initialize, an empty set means "no
  62.      * preference".
  63.      *
  64.      * @private {!Set.<string>}
  65.      */
  66.     this.currentLocales_ = new Set();
  68.     /**
  69.      * A map of maps where:
  70.      *  - The outer map is a mapping from locale code to localizations.
  71.      *  - The inner map is a mapping from id to localized text.
  72.      *
  73.      * @private {!Map.<string, !Map.<string, string>>}
  74.      */
  75.     this.localizations_ = new Map();
  77.     /**
  78.      * The event target that we will wrap so that we can fire events
  79.      * without having to manage the listeners directly.
  80.      *
  81.      * @private {!EventTarget}
  82.      */
  83.     this.events_ = new shaka.util.FakeEventTarget();
  84.   }
  86.   /**
  87.    * @override
  88.    * @export
  89.    */
  90.   addEventListener(type, listener, options) {
  91.     this.events_.addEventListener(type, listener, options);
  92.   }
  94.   /**
  95.    * @override
  96.    * @export
  97.    */
  98.   removeEventListener(type, listener, options) {
  99.     // Apparently Closure says we can be passed a null |option|, but we can't
  100.     // pass a null option, so if we get have a null-like |option|, force it to
  101.     // be undefined.
  102.     this.events_.removeEventListener(type, listener, options || undefined);
  103.   }
  105.   /**
  106.    * @override
  107.    * @export
  108.    */
  109.   dispatchEvent(event) {
  110.     return this.events_.dispatchEvent(event);
  111.   }
  113.   /**
  114.    * Request the localization system to change which locale it serves. If any of
  115.    * of the preferred locales cannot be found, the localization system will fire
  116.    * an event identifying which locales it does not know. The localization
  117.    * system will then continue to operate using the closest matches it has.
  118.    *
  119.    * @param {!Iterable.<string>} locales
  120.    *    The locale codes for the requested locales in order of preference.
  121.    * @export
  122.    */
  123.   changeLocale(locales) {
  124.     const Class = shaka.ui.Localization;
  126.     // Normalize the locale so that matching will be easier. We need to reset
  127.     // our internal set of locales so that we have the same order as the new
  128.     // set.
  129.     this.currentLocales_.clear();
  130.     for (const locale of locales) {
  131.       this.currentLocales_.add(shaka.util.LanguageUtils.normalize(locale));
  132.     }
  134.     this.updateCurrentMap_();
  136.     this.events_.dispatchEvent(new shaka.util.FakeEvent(Class.LOCALE_CHANGED));
  138.     // Check if we have support for the exact locale requested. Even through we
  139.     // will do our best to return the most relevant results, we need to tell
  140.     // app that some data may be missing.
  141.     const missing = shaka.util.Iterables.filter(
  142.         this.currentLocales_,
  143.         (locale) => !this.localizations_.has(locale));
  145.     if (missing.length) {
  146.       /** @type {shaka.ui.Localization.UnknownLocalesEvent} */
  147.       const e = {
  148.         'locales': missing,
  149.       };
  151.       this.events_.dispatchEvent(new shaka.util.FakeEvent(
  152.           Class.UNKNOWN_LOCALES,
  153.           e));
  154.     }
  155.   }
  157.   /**
  158.    * Insert a set of localizations for a single locale. This will amend the
  159.    * existing localizations for the given locale.
  160.    *
  161.    * @param {string} locale
  162.    *   The locale that the localizations should be added to.
  163.    * @param {!Map.<string, string>} localizations
  164.    *   A mapping of id to localized text that should used to modify the internal
  165.    *   collection of localizations.
  166.    * @param {shaka.ui.Localization.ConflictResolution=} conflictResolution
  167.    *   The strategy used to resolve conflicts when the id of an existing entry
  168.    *   matches the id of a new entry. Default to |USE_NEW|, where the new
  169.    *   entry will replace the old entry.
  170.    * @return {!shaka.ui.Localization}
  171.    *   Returns |this| so that calls can be chained.
  172.    * @export
  173.    */
  174.   insert(locale, localizations, conflictResolution) {
  175.     const Class = shaka.ui.Localization;
  176.     const ConflictResolution = shaka.ui.Localization.ConflictResolution;
  177.     const FakeEvent = shaka.util.FakeEvent;
  179.     // Normalize the locale so that matching will be easier.
  180.     locale = shaka.util.LanguageUtils.normalize(locale);
  182.     // Default |conflictResolution| to |USE_NEW| if it was not given. Doing it
  183.     // here because it would create too long of a parameter list.
  184.     if (conflictResolution === undefined) {
  185.       conflictResolution = ConflictResolution.USE_NEW;
  186.     }
  188.     // Make sure we have an entry for the locale because we are about to
  189.     // write to it.
  190.     const table = this.localizations_.get(locale) || new Map();
  191.     localizations.forEach((value, id) => {
  192.       // Set the value if we don't have an old value or if we are to replace
  193.       // the old value with the new value.
  194.       if (!table.has(id) || conflictResolution == ConflictResolution.USE_NEW) {
  195.         table.set(id, value);
  196.       }
  197.     });
  198.     this.localizations_.set(locale, table);
  200.     // The data we use to make our map may have changed, update the map we pull
  201.     // data from.
  202.     this.updateCurrentMap_();
  204.     this.events_.dispatchEvent(new FakeEvent(Class.LOCALE_UPDATED));
  206.     return this;
  207.   }
  209.   /**
  210.    * Set the value under each key in |dictionary| to the resolved value.
  211.    * Convenient for apps with some kind of data binding system.
  212.    *
  213.    * Equivalent to:
  214.    *    for (const key of dictionary.keys()) {
  215.    *      dictionary.set(key, localization.resolve(key));
  216.    *    }
  217.    *
  218.    * @param {!Map.<string, string>} dictionary
  219.    * @export
  220.    */
  221.   resolveDictionary(dictionary) {
  222.     for (const key of dictionary.keys()) {
  223.       // Since we are not changing what keys are in the map, it is safe to
  224.       // update the map while iterating it.
  225.       dictionary.set(key, this.resolve(key));
  226.     }
  227.   }
  229.   /**
  230.    * Request the localized string under the given id. If there is no localized
  231.    * version of the string, then the fallback localization will be given
  232.    * ("en" version). If there is no fallback localization, a non-null empty
  233.    * string will be returned.
  234.    *
  235.    * @param {string} id The id for the localization entry.
  236.    * @return {string}
  237.    * @export
  238.    */
  239.   resolve(id) {
  240.     const Class = shaka.ui.Localization;
  241.     const FakeEvent = shaka.util.FakeEvent;
  243.     /** @type {string} */
  244.     const result = this.currentMap_.get(id);
  246.     // If we have a result, it means that it was found in either the current
  247.     // locale or one of the fall-backs.
  248.     if (result) {
  249.       return result;
  250.     }
  252.     // Since we could not find the result, it means it is missing from a large
  253.     // number of locales. Since we don't know which ones we actually checked,
  254.     // just tell them the preferred locale.
  256.     /** @type {shaka.ui.Localization.UnknownLocalizationEvent} */
  257.     const e = {
  258.       // Make a copy to avoid leaking references.
  259.       'locales': Array.from(this.currentLocales_),
  260.       'missing': id,
  261.     };
  263.     this.events_.dispatchEvent(new FakeEvent(Class.UNKNOWN_LOCALIZATION, e));
  265.     return '';
  266.   }
  268.   /**
  269.    * @private
  270.    */
  271.   updateCurrentMap_() {
  272.     const LanguageUtils = shaka.util.LanguageUtils;
  274.     /** @type {!Map.<string, !Map.<string, string>>} */
  275.     const localizations = this.localizations_;
  276.     /** @type {string} */
  277.     const fallbackLocale = this.fallbackLocale_;
  278.     /** @type {!Iterable.<string>} */
  279.     const preferredLocales = this.currentLocales_;
  281.     /**
  282.      * We want to create a single map that gives us the best possible responses
  283.      * for the current locale. To do this, we will go through be loosest
  284.      * matching locales to the best matching locales. By the time we finish
  285.      * flattening the maps, the best result will be left under each key.
  286.      *
  287.      * Get the locales we should use in order of preference. For example with
  288.      * preferred locales of "elvish-WOODLAND" and "dwarfish-MOUNTAIN" and a
  289.      * fallback of "common-HUMAN", this would look like:
  290.      *
  291.      * new Set([
  292.      *    // Preference 1
  293.      *    'elvish-WOODLAND',
  294.      *    // Preference 1 Base
  295.      *    'elvish',
  296.      *    // Preference 1 Siblings
  297.      *    'elvish-WOODLAND', 'elvish-WESTWOOD', 'elvish-MARSH,
  298.      *    // Preference 2
  299.      *    'dwarfish-MOUNTAIN',
  300.      *    // Preference 2 base
  301.      *    'dwarfish',
  302.      *    // Preference 2 Siblings
  303.      *    'dwarfish-MOUNTAIN', 'dwarfish-NORTH', "dwarish-SOUTH",
  304.      *    // Fallback
  305.      *    'common-HUMAN',
  306.      * ])
  307.      *
  308.      * @type {!Set.<string>}
  309.      */
  310.     const localeOrder = new Set();
  312.     for (const locale of preferredLocales) {
  313.       localeOrder.add(locale);
  314.       localeOrder.add(LanguageUtils.getBase(locale));
  316.       const siblings = shaka.util.Iterables.filter(
  317.           localizations.keys(),
  318.           (other) => LanguageUtils.areSiblings(other, locale));
  320.       // Sort the siblings so that they will always appear in the same order
  321.       // regardless of the order of |localizations|.
  322.       siblings.sort();
  323.       for (const locale of siblings) { localeOrder.add(locale); }
  325.       const children = shaka.util.Iterables.filter(
  326.           localizations.keys(),
  327.           (other) => LanguageUtils.getBase(other) == locale);
  329.       // Sort the children so that they will always appear in the same order
  330.       // regardless of the order of |localizations|.
  331.       children.sort();
  332.       for (const locale of children) { localeOrder.add(locale); }
  333.     }
  335.     // Finally we add our fallback (something that should have all expected
  336.     // entries).
  337.     localeOrder.add(fallbackLocale);
  339.     // Add all the sibling maps.
  340.     const mergeOrder = [];
  341.     for (const locale of localeOrder) {
  342.       const map = localizations.get(locale);
  343.       if (map) { mergeOrder.push(map); }
  344.     }
  346.     // We need to reverse the merge order. We build the order based on most
  347.     // preferred to least preferred. However, the merge will work in the
  348.     // opposite order so we must reverse our maps so that the most preferred
  349.     // options will be applied last.
  350.     mergeOrder.reverse();
  352.     // Merge all the options into our current map.
  353.     this.currentMap_.clear();
  354.     for (const map of mergeOrder) {
  355.       map.forEach((value, key) => {
  356.         this.currentMap_.set(key, value);
  357.       });
  358.     }
  360.     // Go through every key we have and see if any preferred locales are
  361.     // missing entries. This will allow app developers to find holes in their
  362.     // localizations.
  364.     /** @type {!Iterable.<string>} */
  365.     const allKeys = this.currentMap_.keys();
  367.     /** @type {!Set.<string>} */
  368.     const missing = new Set();
  370.     for (const locale of this.currentLocales_) {
  371.       // Make sure we have a non-null map. The diff will be easier that way.
  372.       const map = this.localizations_.get(locale) || new Map();
  373.       shaka.ui.Localization.findMissingKeys_(map, allKeys, missing);
  374.     }
  376.     if (missing.size > 0) {
  377.       /** @type {shaka.ui.Localization.MissingLocalizationsEvent} */
  378.       const e = {
  379.         // Make a copy of the preferred locales to avoid leaking references.
  380.         'locales': Array.from(preferredLocales),
  381.         // Because most people like arrays more than sets, convert the set to
  382.         // an array.
  383.         'missing': Array.from(missing),
  384.       };
  386.       this.events_.dispatchEvent(new shaka.util.FakeEvent(
  387.           shaka.ui.Localization.MISSING_LOCALIZATIONS,
  388.           e));
  389.     }
  390.   }
  392.   /**
  393.    * Go through a map and add all the keys that are in |keys| but not in
  394.    * |map| to |missing|.
  395.    *
  396.    * @param {!Map.<string, string>} map
  397.    * @param {!Iterable.<string>} keys
  398.    * @param {!Set.<string>} missing
  399.    * @private
  400.    */
  401.   static findMissingKeys_(map, keys, missing) {
  402.     for (const key of keys) {
  403.       // Check if the value is missing so that we are sure that it does not
  404.       // have a value. We get the value and not just |has| so that a null or
  405.       // empty string will fail this check.
  406.       if (!map.get(key)) {
  407.         missing.add(key);
  408.       }
  409.     }
  410.   }
  411. };
  414. /**
  415.  * An enum for how the localization system should resolve conflicts between old
  416.  * translations and new translations.
  417.  *
  418.  * @enum {number}
  419.  * @export
  420.  */
  421. shaka.ui.Localization.ConflictResolution = {
  422.   'USE_OLD': 0,
  423.   'USE_NEW': 1,
  424. };
  426. /**
  427.  * The event name for when locales were requested, but we could not find any
  428.  * entries for them. The localization system will continue to use the closest
  429.  * matches it has.
  430.  *
  431.  * @const {string}
  432.  * @export
  433.  */
  434. shaka.ui.Localization.UNKNOWN_LOCALES = 'unknown-locales';
  436. /**
  437.  * The event name for when an entry could not be found in the preferred locale,
  438.  * related locales, or the fallback locale.
  439.  *
  440.  * @const {string}
  441.  * @export
  442.  */
  443. shaka.ui.Localization.UNKNOWN_LOCALIZATION = 'unknown-localization';
  445. /**
  446.  * The event name for when entries are missing from the user's preferred
  447.  * locale, but we were able to find an entry in a related locale or the fallback
  448.  * locale.
  449.  *
  450.  * @const {string}
  451.  * @export
  452.  */
  453. shaka.ui.Localization.MISSING_LOCALIZATIONS = 'missing-localizations';
  455. /**
  456.  * The event name for when a new locale has been requested and any previously
  457.  * resolved values should be updated.
  458.  *
  459.  * @const {string}
  460.  * @export
  461.  */
  462. shaka.ui.Localization.LOCALE_CHANGED = 'locale-changed';
  464. /**
  465.  * The event name for when |insert| was called and it changed entries that could
  466.  * affect previously resolved values.
  467.  *
  468.  * @const {string}
  469.  * @export
  470.  */
  471. shaka.ui.Localization.LOCALE_UPDATED = 'locale-updated';
  473. /**
  474.  * @typedef {{
  475.  *   'locales': !Array.<string>
  476.  * }}
  477.  *
  478.  * @property {!Array.<string>} locales
  479.  *    The locales that the user wanted but could not be found.
  480.  * @exportDoc
  481.  */
  482. shaka.ui.Localization.UnknownLocalesEvent;
  484. /**
  485.  * @typedef {{
  486.  *   'locales': !Array.<string>,
  487.  *   'missing': string
  488.  * }}
  489.  *
  490.  * @property {!Array.<string>} locales
  491.  *    The locales that the user wanted.
  492.  * @property {string} missing
  493.  *    The id of the unknown entry.
  494.  * @exportDoc
  495.  */
  496. shaka.ui.Localization.UnknownLocalizationEvent;
  498. /**
  499.  * @typedef {{
  500.  *   'locales': !Array.<string>,
  501.  *   'missing': !Array.<string>
  502.  * }}
  503.  *
  504.  * @property {string} locale
  505.  *    The locale that the user wanted.
  506.  * @property {!Array.<string>} missing
  507.  *    The ids of the missing entries.
  508.  * @exportDoc
  509.  */
  510. shaka.ui.Localization.MissingLocalizationsEvent;