remote/marionette/l10n.sys.mjs

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 /**
   6  * An API which allows Marionette to handle localized content.
   7  *
   8  * The localization (https://mzl.la/2eUMjyF) of UI elements in Gecko
   9  * based applications is done via entities and properties. For static
  10  * values entities are used, which are located in .dtd files. Whereby for
  11  * dynamically updated content the values come from .property files. Both
  12  * types of elements can be identifed via a unique id, and the translated
  13  * content retrieved.
  14  */
  15
  16 const lazy = {};
  17
  18 ChromeUtils.defineESModuleGetters(lazy, {
  19   error: "chrome://remote/content/shared/webdriver/Errors.sys.mjs",
  20 });
  21
  22 ChromeUtils.defineLazyGetter(lazy, "domParser", () => {
  23   const parser = new DOMParser();
  24   parser.forceEnableDTD();
  25   return parser;
  26 });
  27
  28 /** @namespace */
  29 export const l10n = {};
  30
  31 /**
  32  * Retrieve the localized string for the specified entity id.
  33  *
  34  * Example:
  35  *     localizeEntity(["chrome://branding/locale/brand.dtd"], "brandShortName")
  36  *
  37  * @param {Array.<string>} urls
  38  *     Array of .dtd URLs.
  39  * @param {string} id
  40  *     The ID of the entity to retrieve the localized string for.
  41  *
  42  * @returns {string}
  43  *     The localized string for the requested entity.
  44  */
  45 l10n.localizeEntity = function (urls, id) {
  46   // Build a string which contains all possible entity locations
  47   let locations = [];
  48   urls.forEach((url, index) => {
  49     locations.push(`<!ENTITY % dtd_${index} SYSTEM "${url}">%dtd_${index};`);
  50   });
  51
  52   // Use the DOM parser to resolve the entity and extract its real value
  53   let header = `<?xml version="1.0"?><!DOCTYPE elem [${locations.join("")}]>`;
  54   let elem = `<elem id="elementID">&${id};</elem>`;
  55   let doc = lazy.domParser.parseFromString(header + elem, "text/xml");
  56   let element = doc.querySelector("elem[id='elementID']");
  57
  58   if (element === null) {
  59     throw new lazy.error.NoSuchElementError(
  60       `Entity with id='${id}' hasn't been found`
  61     );
  62   }
  63
  64   return element.textContent;
  65 };
  66
  67 /**
  68  * Retrieve the localized string for the specified property id.
  69  *
  70  * Example:
  71  *
  72  *     localizeProperty(
  73  *         ["chrome://global/locale/findbar.properties"], "FastFind");
  74  *
  75  * @param {Array.<string>} urls
  76  *     Array of .properties URLs.
  77  * @param {string} id
  78  *     The ID of the property to retrieve the localized string for.
  79  *
  80  * @returns {string}
  81  *     The localized string for the requested property.
  82  */
  83 l10n.localizeProperty = function (urls, id) {
  84   let property = null;
  85
  86   for (let url of urls) {
  87     let bundle = Services.strings.createBundle(url);
  88     try {
  89       property = bundle.GetStringFromName(id);
  90       break;
  91     } catch (e) {}
  92   }
  93
  94   if (property === null) {
  95     throw new lazy.error.NoSuchElementError(
  96       `Property with ID '${id}' hasn't been found`
  97     );
  98   }
  99
 100   return property;
 101 };