Add goog.i18n.messages.declareIcuTemplate() to closure-library

This is a new API for declaring messages that use ICU message format.

It has long been possible to use `goog.getMsg()` to declare messages
that use ICU format, but it wasn't possible to provide example
or original_code text for the ICU placeholders.

It has been a source of some confusion that `goog.getMsg()` effectively
supports 2 quite different placeholder formats, one for compile-time
and one for runtime (ICU).

Going forward, users should prefer using `declareIcuTemplate()`
for ICU-formatted messages. We hope to eventually make it an error
to specify an ICU-formatted message to `goog.getMsg()`.

RELNOTES[NEW]: Add goog.i18n.messages.declareIcuTemplate() as a better way to declare ICU-formatted messages.

PiperOrigin-RevId: 488785352
Change-Id: Ibcdf9745a0ae743353a5c955ac09d6658274e2d0

Author: brad4d

closure/goog/i18n/BUILD

@@ -31,6 +31,7 @@ closure_js_library(
         ":listsymbolsext",
         ":localefeature",
         ":messageformat",
+        ":messages",
         ":mime",
         ":numberformat",
         ":numberformatsymbols",
@@ -301,6 +302,13 @@ closure_js_library(
     ],
 )
 
+closure_js_library(
+    name = "messages",
+    srcs = ["messages.js"],
+    lenient = True,
+    deps = ["//closure/goog/asserts"],
+)
+
 closure_js_library(
     name = "mime",
     srcs = ["mime.js"],

closure/goog/i18n/messages.js

@@ -0,0 +1,315 @@
+/**
+ * @license
+ * Copyright The Closure Library Authors.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Support for declaring localizable messages.
+ */
+
+goog.module('goog.i18n.messages');
+
+const {assert} = goog.require('goog.asserts');
+
+/**
+ * Options bag type for `declareIcuTemplate()` options argument.
+ *
+ * It is important to note that these options need to be known at compile time,
+ * so they must always be provided to `declareIcuTmplate()` as an actual object
+ * literal in the function call. Otherwise, closure-compiler will report an
+ * error.
+ *
+ * @record
+ */
+const IcuTemplateOptions = function() {};
+
+/**
+ * Required text describing how the message will be used.
+ *
+ * Translators will use this information to help them understand and translate
+ * the message.
+ *
+ * @type {string}
+ */
+IcuTemplateOptions.prototype.description;
+
+/**
+ * Optional text used to differentiate messages with identical original text but
+ * different meanings.
+ *
+ * This field should usually be left undefined.
+ * It should only be used when there exist 2 or more messages that have
+ * identical original text but are used in very different ways, so that one
+ * translation won't work for both.
+ *
+ * For example, maybe "close" needs to be translated in one place as "to close
+ * something" but in another as "these things are close to each other".
+ *
+ * In such a case, you would specify clarifying text in the "meaning" field. It
+ * is different from the "description" field in that "meaning" is used when
+ * computing the unique message identifier, but "description" is not. Although
+ * this field may be shown to translators, its primary function is just to
+ * serve as a point of difference to disambiguate 2 otherwise identical
+ * messages.
+ *
+ * @type {undefined|string}
+ */
+IcuTemplateOptions.prototype.meaning;
+
+/**
+ * Associates placeholder names with example values.
+ *
+ * closure-compiler uses this as the contents of the `<ex>` tag in the
+ * XMB file it generates or defaults to `-` for historical reasons.
+ *
+ * * Must be an object literal.
+ * * Ignored at runtime.
+ * * Keys are placeholder names.
+ * * Values are string literals containing example placeholder values.
+ *   (e.g. "George McFly" for a name placeholder)
+ *
+ * @type {!Object<string, string>|undefined}
+ */
+IcuTemplateOptions.prototype.example;
+
+/**
+ * Associates placeholder names with strings showing how their values are
+ * obtained.
+ *
+ * This field is intended for use in automatically generated JS code.
+ * Human-written code should use meaningful placeholder names instead.
+ *
+ * closure-compiler uses this as the contents of the `<ph>` tag in the
+ * XMB file it generates or defaults to `-` for historical reasons.
+ *
+ * * Must be an object literal.
+ * * Ignored at runtime.
+ * * Keys are placeholder names.
+ * * Values are string literals indicating how the value is obtained.
+ * * Typically this is a snippet of source code.
+ *
+ * @type {!Object<string, string>|undefined}
+ */
+IcuTemplateOptions.prototype.original_code;
+
+/**
+ * Declare a message template using ICU format.
+ *
+ * See https://unicode-org.github.io/icu/userguide/format_parse/messages/
+ *
+ * When run uncompiled, the template string and options will be checked for
+ * easy-to-spot programming errors. If there are none, the template string will
+ * be returned unmodified. Otherwise, an exception will be thrown.
+ *
+ * The template string will probably contain ICU-formatted placeholders
+ * (e.g. "Hi, {NAME}"). The return value from this function will still contain
+ * those. It should be passed to a message formatting API, such as
+ * `goog.i18n.MessageFormat` in order to specify the runtime values to
+ * substitute and produce the final message to display to users.
+ *
+ * IMPORTANT: It is an error to use closure-style placeholder syntax
+ * (e.g. "Hi, {$NAME}" - note the '{$'), such as is used by `goog.getMsg()` for
+ * compile-time substitution of placeholder values.
+ *
+ * At compile time, closure-compiler will look up the localized form of this
+ * message in a translation bundle file (XTB), and replace this function call
+ * with a string literal containing the translated template.
+ *
+ * The XTB file is generated by some combination of human translators and
+ * automated tools based on information they receive in an XMB file.
+ *
+ * The closure-compiler message extraction tool will generate an XMB file
+ * from messages declared in JS source code, including calls to this function.
+ *
+ * The message element produced for a call to this function will contain a
+ * `<ph>` (placeholder) element for each ICU placeholder found in the template
+ * string.
+ *
+ * e.g.
+ *
+ * ```javascript
+ * const MSG_HI = declareIcuTemplate(
+ *     'Hi, {START_BOLD}{NAME}{END_BOLD}!',
+ *     {
+ *       description: 'Say "Hi" to the user.',
+ *       example: {
+ *         'NAME': 'Jane'
+ *       },
+ *       original_code: {
+ *         // Shown to make clear how it appears in the XMB file.
+ *         // Hand-written JS code should not use this.
+ *         'NAME': 'user.getName()'
+ *       }
+ *     });
+ * ```
+ *
+ * May generate an XMB element like this:
+ *
+ * ```xml
+ * <msg
+ *     id='3346156045081344548'
+ *     name='MSG_HI'
+ *     desc='Say "Hi" to the user.'
+ *     >Hi, {START_BOLD}<ph
+ * name="NAME"><ex>Jane</ex>user.getName()</ph>{END_BOLD}!</msg>
+ * ```
+ *
+ * IMPORTANT: The options argument and the values it contains must all be
+ * literal values. The message extraction tool is not able to evaluate
+ * expressions or look up variable values.
+ *
+ * Note that in the example above there are ICU placeholders that are not
+ * converted into `<ph>` placeholder elements in the XMB file. When no example
+ * or original code text is given, there is no need to create such elements.
+ * When only one of these two values is given, the other will default to "-"
+ * for historical reasons.
+ *
+ *
+ * The "original_code" option is intended for use when automatically generating
+ * JS code from some other source, such as an Angular template, where it is
+ * difficult or impossible for the human author to specify a meaningful
+ * placeholder name. Hand-written JS code should just use a meaningful
+ * placeholder name instead.
+ *
+ * The 'original_code' text and the 'example' text are shown to human
+ * translators to give them more context about the meaning of the message.
+ * They are not used in any other way by closure-compiler or closure-library.
+ *
+ * @param {string} templateString
+ * @param {!IcuTemplateOptions} options
+ * @return {string}
+ */
+function declareIcuTemplate(templateString, options) {
+  // The options are only really used by the compiler when extracting messages
+  // into an XMB file for translation. However, we'll check for errors now,
+  // in order to help the developer discover they've made a mistake ASAP.
+  // Compilation will completely replace calls to this method with static
+  // strings, so the cost of these checks will only be paid during testing
+  // and development.
+  assertDeclareIcuTemplateParametersAreValid(templateString, options);
+  return templateString;
+}
+
+/**
+ * Properties that are valid to include in the options bag argument to
+ * `declareIcuTemplate()`.
+ *
+ * @type {!Set<string>}
+ */
+const VALID_OPTIONS =
+    new Set(['description', 'meaning', 'example', 'original_code']);
+
+/**
+ * Throw an exception if the parameters are not valid for a `declareIcuTemplate`
+ * function call.
+ *
+ * @param {string} templateString
+ * @param {!IcuTemplateOptions} options
+ */
+function assertDeclareIcuTemplateParametersAreValid(templateString, options) {
+  // This check exists to alert developers to possible problems with their
+  // `declareIcuTemplate()` message calls during uncompiled execution.
+  // During compilation closure-compiler will perform these same checks and
+  // replace all calls to `declareIcuTemplate()` with string literals.
+  if (COMPILED) return;
+
+  assertNoClosureStylePlaceholdersInIcuTemplate(templateString);
+  const icuPlaceholderNames = gatherIcuPlaceholderNames(templateString);
+
+  const description = options.description;
+  assert(description, 'no description supplied');
+  assert(
+      typeof description == 'string', 'invalid description: "%s"', description);
+
+  const meaning = options.meaning;
+  assert(
+      !meaning || typeof meaning == 'string', 'invalid meaning: "%s"', meaning);
+
+  const exampleMap = options.example;
+  if (exampleMap) {
+    assert(
+        typeof exampleMap == 'object', 'invalid example map: "%s"', exampleMap);
+    assertValidPlaceholderMap('example', exampleMap, icuPlaceholderNames);
+  }
+
+  const originalCodeMap = options.original_code;
+  if (originalCodeMap) {
+    assert(
+        typeof originalCodeMap == 'object', 'invalid original_code map: "%s"',
+        originalCodeMap);
+    assertValidPlaceholderMap(
+        'original_code', originalCodeMap, icuPlaceholderNames);
+  }
+
+  for (const propName of Object.keys(options)) {
+    assert(VALID_OPTIONS.has(propName), 'unknown option name: "%s"', propName);
+  }
+}
+
+/**
+ * Throw an exception if the parameters are not valid for a `declareIcuTemplate`
+ * function call.
+ *
+ * @param {string} mapName 'example' or 'original_code'
+ * @param {!Object<string>} placeholderMap Map from placeholder names to string
+ *     values
+ * @param {!Set<string>} allPlaceholderNames All known placeholder names
+ */
+function assertValidPlaceholderMap(
+    mapName, placeholderMap, allPlaceholderNames) {
+  for (const placeholderName of Object.keys(placeholderMap)) {
+    assert(
+        allPlaceholderNames.has(placeholderName),
+        '%s: unknown placeholder: "%s"', mapName, placeholderName);
+    const placeholderValue = placeholderMap[placeholderName];
+    assert(
+        typeof placeholderValue == 'string', 'invalid %s value for %s: "%s"',
+        mapName, placeholderName, placeholderValue);
+  }
+}
+
+
+/** Matches a single closure-style placeholder. */
+const CLOSURE_PLACEHOLDER_RE = /\{\$([^}]+)}/;
+
+/**
+ * @param {string} icuTemplate
+ * @throws an AssertionError if the string contains closure-style placeholders
+ *   (`'{$name} is a closure-style placeholder'`)
+ */
+function assertNoClosureStylePlaceholdersInIcuTemplate(icuTemplate) {
+  const match = CLOSURE_PLACEHOLDER_RE.exec(icuTemplate);
+  assert(
+      match == null,
+      'closure-style placeholder: "%s" found in ICU template: "%s"',
+      match && match[0], icuTemplate);
+}
+
+/**
+ * Matches globally for ICU-style placeholder names.
+ *
+ * Capturing group #1 contains the the placeholder name for each match.
+ */
+const ICU_PLACEHOLDER_GLOBAL_RE = /\{([a-z_]\w*)}/ig;
+
+/**
+ * @param {string} icuTemplate
+ * @return {!Set<string>} contains placeholder names found in icuTemplate
+ */
+function gatherIcuPlaceholderNames(icuTemplate) {
+  const resultSet = new Set();
+  let match = null;
+
+  while (match = ICU_PLACEHOLDER_GLOBAL_RE.exec(icuTemplate)) {
+    resultSet.add(match[1]);
+  }
+  return resultSet;
+}
+
+// TODO(bradfordcsmith): Add another method to this module that will serve to
+//     replace goog.getMsg(), so we can drop that method from base.js.
+exports = {
+  declareIcuTemplate,
+  IcuTemplateOptions
+};