feat(ivy): i18n - reorganize entry-points for better reuse (#32488)

This is a refactoring that moves the source code around to provide a better
platform for adding the compile-time inlining.

1. Move the global side-effect import from the primary entry-point to a
   secondary entry-point @angular/localize/init.

   This has two benefits: first it allows the top level entry-point to
   contain tree-shakable shareable code; second it gives the side-effect
   import more of an "action" oriented name, which indicates that importing
   it does something tangible

2. Move all the source code into the top src folder, and import the localize
   related functions into the localize/init/index.ts entry-point.

   This allows the different parts of the package to share code without
   a proliferation of secondary entry-points (i.e. localize/utils).

3. Avoid publicly exporting any utilities at this time - the only public
   API at this point are the global `$localize` function and the two runtime
   helpers `loadTranslations()` and `clearTranslations()`.
   This does not mean that we will not expose additional helpers for 3rd
   party tooling in the future, but it avoid us preemptively exposing
   something that we might want to change in the near future.

Notes:

It is not possible to have the `$localize` code in the same Bazel package
as the rest of the code. If we did this, then the bundled `@angular/localize/init`
entry-point code contains all of the helper code, even though most of it is not used.

Equally it is not possible to have the `$localize` types (i.e. `LocalizeFn`
and `TranslateFn`) defined in the `@angular/localize/init` entry-point because
these types are needed for the runtime code, which is inside the primary
entry-point. Importing them from `@angular/localize/init` would run the
side-effect.

The solution is to have a Bazel sub-package at `//packages/localize/src/localize`
which contains these types and the `$localize` function implementation.
The primary `//packages/localize` entry-point imports the types without
any side-effect.
The secondary `//packages/localize/init` entry-point imports the `$localize`
function and attaches it to the global scope as a side-effect, without
bringing with it all the other utility functions.

BREAKING CHANGES:

The entry-points have changed:

* To attach the `$localize` function to the global scope import from
`@angular/localize/init`. Previously it was `@angular/localize`.

* To access the `loadTranslations()` and `clearTranslations()` functions,
import from `@angular/localize`. Previously it was `@angular/localize/run_time`.

PR Close #32488

packages/localize/src/localize/BUILD.bazel

@@ -0,0 +1,16 @@
+load("//tools:defaults.bzl", "ts_library")
+
+package(default_visibility = ["//visibility:public"])
+
+ts_library(
+    name = "localize",
+    srcs = glob(
+        [
+            "**/*.ts",
+        ],
+    ),
+    module_name = "@angular/localize/src/localize",
+    deps = [
+        "@npm//@types/node",
+    ],
+)

packages/localize/src/localize/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export {_global} from './src/global';
+export {$localize, LocalizeFn, TranslateFn} from './src/localize';

packages/localize/src/localize/test/BUILD.bazel

@@ -0,0 +1,24 @@
+load("//tools:defaults.bzl", "jasmine_node_test", "ts_library")
+
+ts_library(
+    name = "test_lib",
+    testonly = True,
+    srcs = glob(
+        ["*_spec.ts"],
+    ),
+    deps = [
+        "//packages:types",
+        "//packages/localize/src/localize",
+    ],
+)
+
+jasmine_node_test(
+    name = "test",
+    bootstrap = [
+        "angular/tools/testing/init_node_no_angular_spec.js",
+    ],
+    deps = [
+        ":test_lib",
+        "//tools/testing:node_no_angular",
+    ],
+)

packages/localize/src/localize/test/localize_spec.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {$localize, TranslateFn} from '../src/localize';
+
+describe('$localize tag', () => {
+  describe('with no `translate()` defined (the default)', () => {
+    it('should render template literals as-is', () => {
+      expect($localize.translate).toBeUndefined();
+      expect($localize `abc`).toEqual('abc');
+      expect($localize `abc${1 + 2 + 3}`).toEqual('abc6');
+      expect($localize `abc${1 + 2 + 3}def`).toEqual('abc6def');
+      expect($localize `abc${1 + 2 + 3}def${4 + 5 + 6}`).toEqual('abc6def15');
+      const getName = () => 'World';
+      expect($localize `Hello, ${getName()}!`).toEqual('Hello, World!');
+    });
+
+    it('should strip placeholder names from message parts', () => {
+      expect($localize.translate).toBeUndefined();
+      expect($localize `abc${1 + 2 + 3}:ph1:def${4 + 5 + 6}:ph2:`).toEqual('abc6def15');
+    });
+
+    it('should ignore escaped placeholder name marker', () => {
+      expect($localize.translate).toBeUndefined();
+      expect($localize `abc${1 + 2 + 3}\:ph1:def${4 + 5 + 6}\:ph2:`).toEqual('abc6:ph1:def15:ph2:');
+    });
+  });
+
+  describe('with `translate()` defined as an identity', () => {
+    beforeEach(() => { $localize.translate = identityTranslate; });
+    afterEach(() => { $localize.translate = undefined; });
+
+    it('should render template literals as-is', () => {
+
+      expect($localize `abc`).toEqual('abc');
+      expect($localize `abc${1 + 2 + 3}`).toEqual('abc6');
+      expect($localize `abc${1 + 2 + 3}def`).toEqual('abc6def');
+      expect($localize `abc${1 + 2 + 3}def${4 + 5 + 6}`).toEqual('abc6def15');
+      const getName = () => 'World';
+      expect($localize `Hello, ${getName()}!`).toEqual('Hello, World!');
+    });
+  });
+
+  describe('with `translate()` defined to upper-case messageParts', () => {
+    beforeEach(() => { $localize.translate = upperCaseTranslate; });
+    afterEach(() => { $localize.translate = undefined; });
+
+    it('should render template literals with messages upper-cased', () => {
+
+      expect($localize `abc`).toEqual('ABC');
+      expect($localize `abc${1 + 2 + 3}`).toEqual('ABC6');
+      expect($localize `abc${1 + 2 + 3}def`).toEqual('ABC6DEF');
+      expect($localize `abc${1 + 2 + 3}def${4 + 5 + 6}`).toEqual('ABC6DEF15');
+      const getName = () => 'World';
+      expect($localize `Hello, ${getName()}!`).toEqual('HELLO, World!');
+    });
+  });
+
+  describe('with `translate()` defined to reverse expressions', () => {
+    beforeEach(() => { $localize.translate = reverseTranslate; });
+    afterEach(() => { $localize.translate = undefined; });
+
+    it('should render template literals with expressions reversed', () => {
+      const getName = () => 'World';
+      expect($localize `abc${1 + 2 + 3}def${4 + 5 + 6} - Hello, ${getName()}!`)
+          .toEqual('abcWorlddef15 - Hello, 6!');
+    });
+  });
+});
+
+function makeTemplateObject(cooked: string[], raw: string[]): TemplateStringsArray {
+  Object.defineProperty(cooked, 'raw', {value: raw});
+  return cooked as any;
+}
+
+const identityTranslate: TranslateFn = function(
+    messageParts: TemplateStringsArray, expressions: readonly any[]) {
+  return [messageParts, expressions];
+};
+
+const upperCaseTranslate: TranslateFn = function(
+    messageParts: TemplateStringsArray, expressions: readonly any[]) {
+  return [
+    makeTemplateObject(
+        Array.from(messageParts).map((part: string) => part.toUpperCase()),
+        messageParts.raw.map((part: string) => part.toUpperCase())),
+    expressions
+  ];
+};
+
+const reverseTranslate: TranslateFn = function(
+    messageParts: TemplateStringsArray, expressions: readonly any[]) {
+  expressions = Array.from(expressions).reverse();
+  return [messageParts, expressions];
+};

packages/localize/src/translate.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {LocalizeFn} from './localize';
+import {ParsedTranslation, TargetMessage, TranslationKey, parseTranslation, translate as _translate} from './utils/translations';
+
+/**
+ * We augment the `$localize` object to also store the translations.
+ *
+ * Note that because the TRANSLATIONS are attached to a global object, they will be shared between
+ * all applications that are running in a single page of the browser.
+ */
+declare const $localize: LocalizeFn&{TRANSLATIONS: Record<string, ParsedTranslation>};
+
+/**
+ * Load translations for `$localize`.
+ *
+ * The given `translations` are processed and added to a lookup based on their translation key.
+ * A new translation will overwrite a previous translation if it has the same key.
+ *
+ * @publicApi
+ */
+export function loadTranslations(translations: Record<TranslationKey, TargetMessage>) {
+  // Ensure the translate function exists
+  if (!$localize.translate) {
+    $localize.translate = translate;
+  }
+  if (!$localize.TRANSLATIONS) {
+    $localize.TRANSLATIONS = {};
+  }
+  Object.keys(translations).forEach(key => {
+    $localize.TRANSLATIONS[key] = parseTranslation(translations[key]);
+  });
+}
+
+/**
+ * Remove all translations for `$localize`.
+ *
+ * @publicApi
+ */
+export function clearTranslations() {
+  $localize.TRANSLATIONS = {};
+}
+
+/**
+ * Translate the text of the given message, using the loaded translations.
+ *
+ * This function may reorder (or remove) substitutions as indicated in the matching translation.
+ */
+export function translate(messageParts: TemplateStringsArray, substitutions: readonly any[]):
+    [TemplateStringsArray, readonly any[]] {
+  return _translate($localize.TRANSLATIONS, messageParts, substitutions);
+}

packages/localize/src/utils/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * The character used to mark the start and end of a placeholder name in a `$localize` tagged
+ * string.
+ *
+ * For example:
+ *
+ * ```
+ * $localize`Hello, ${title}:title:!`;
+ * ```
+ */
+export const PLACEHOLDER_NAME_MARKER = ':';

packages/localize/src/utils/messages.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {PLACEHOLDER_NAME_MARKER} from './constants';
+import {TranslationKey} from './translations';
+
+/**
+ * A string containing a translation source message.
+ *
+ * I.E. the message that indicates what will be translated from.
+ *
+ * Uses `{$placeholder-name}` to indicate a placeholder.
+ */
+export type SourceMessage = string;
+
+/**
+ * Information parsed from a `$localize` tagged string that is used to translate it.
+ *
+ * For example:
+ *
+ * ```
+ * const name = 'Jo Bloggs';
+ * $localize`Hello ${name}:title!`;
+ * ```
+ *
+ * May be parsed into:
+ *
+ * ```
+ * {
+ *   translationKey: 'Hello {$title}!',
+ *   substitutions: { title: 'Jo Bloggs' },
+ * }
+ * ```
+ */
+export interface ParsedMessage {
+  /**
+   * The key used to look up the appropriate translation target.
+   */
+  translationKey: TranslationKey;
+  /**
+   * A mapping of placeholder names to substitution values.
+   */
+  substitutions: Record<string, any>;
+}
+
+/**
+ * Parse a `$localize` tagged string into a structure that can be used for translation.
+ *
+ * See `ParsedMessage` for an example.
+ */
+export function parseMessage(
+    messageParts: TemplateStringsArray, expressions: readonly any[]): ParsedMessage {
+  const replacements: {[placeholderName: string]: any} = {};
+  let translationKey = messageParts[0];
+  for (let i = 1; i < messageParts.length; i++) {
+    const messagePart = messageParts[i];
+    const expression = expressions[i - 1];
+    // There is a problem with synthesizing template literals in TS.
+    // It is not possible to provide raw values for the `messageParts` and TS is not able to compute
+    // them since this requires access to the string in its original (non-existent) source code.
+    // Therefore we fall back on the non-raw version if the raw string is empty.
+    // This should be OK because synthesized nodes only come from the template compiler and they
+    // will always contain placeholder name information.
+    // So there will be no escaped placeholder marker character (`:`) directly after a substitution.
+    if ((messageParts.raw[i] || messagePart).charAt(0) === PLACEHOLDER_NAME_MARKER) {
+      const endOfPlaceholderName = messagePart.indexOf(PLACEHOLDER_NAME_MARKER, 1);
+      const placeholderName = messagePart.substring(1, endOfPlaceholderName);
+      translationKey += `{$${placeholderName}}${messagePart.substring(endOfPlaceholderName + 1)}`;
+      replacements[placeholderName] = expression;
+    } else {
+      const placeholderName = `ph_${i}`;
+      translationKey += `{$${placeholderName}}${messagePart}`;
+      replacements[placeholderName] = expression;
+    }
+  }
+  return {translationKey, substitutions: replacements};
+}

packages/localize/src/utils/translations.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {PLACEHOLDER_NAME_MARKER} from './constants';
+import {SourceMessage, parseMessage} from './messages';
+
+/**
+ * A key used to lookup a `TargetMessage` in a hash map.
+ */
+export type TranslationKey = SourceMessage;
+
+/**
+ * A string containing a translation target message.
+ *
+ * I.E. the message that indicates what will be translated to.
+ *
+ * Uses `{$placeholder-name}` to indicate a placeholder.
+ */
+export type TargetMessage = string;
+
+/**
+ * A translation message that has been processed to extract the message parts and placeholders.
+ */
+export interface ParsedTranslation {
+  messageParts: TemplateStringsArray;
+  placeholderNames: string[];
+}
+
+/**
+ * The internal structure used by the runtime localization to translate messages.
+ */
+export type ParsedTranslations = Record<TranslationKey, ParsedTranslation>;
+
+
+/**
+ * Translate the text of the `$localize` tagged-string (i.e. `messageParts` and
+ * `substitutions`) using the given `translations`.
+ *
+ * The tagged-string is parsed to extract its `translationKey` which is used to find an appropriate
+ * `ParsedTranslation`.
+ *
+ * If one is found then it is used to translate the message into a new set of `messageParts` and
+ * `substitutions`.
+ * The translation may reorder (or remove) substitutions as appropriate.
+ *
+ * If no translation matches then the original `messageParts` and `substitutions` are returned
+ */
+export function translate(
+    translations: Record<string, ParsedTranslation>, messageParts: TemplateStringsArray,
+    substitutions: readonly any[]): [TemplateStringsArray, readonly any[]] {
+  const message = parseMessage(messageParts, substitutions);
+  const translation = translations[message.translationKey];
+  if (translation !== undefined) {
+    return [
+      translation.messageParts,
+      translation.placeholderNames.map(placeholder => message.substitutions[placeholder])
+    ];
+  } else {
+    return [messageParts, substitutions];
+  }
+}
+
+/**
+ * Parse the `messageParts` and `placeholderNames` out of a target `message`.
+ *
+ * Used by `loadTranslations()` to convert target message strings into a structure that is more
+ * appropriate for doing translation.
+ *
+ * @param message the message to be parsed.
+ */
+export function parseTranslation(message: TargetMessage): ParsedTranslation {
+  const parts = message.split(/{\$([^}]*)}/);
+  const messageParts = [parts[0]];
+  const placeholderNames: string[] = [];
+  for (let i = 1; i < parts.length - 1; i += 2) {
+    placeholderNames.push(parts[i]);
+    messageParts.push(`${parts[i + 1]}`);
+  }
+  const rawMessageParts =
+      messageParts.map(part => part.charAt(0) === PLACEHOLDER_NAME_MARKER ? '\\' + part : part);
+  return {messageParts: makeTemplateObject(messageParts, rawMessageParts), placeholderNames};
+}
+
+/**
+ * Create the specialized array that is passed to tagged-string tag functions.
+ *
+ * @param cooked The message parts with their escape codes processed.
+ * @param raw The message parts with their escaped codes as-is.
+ */
+export function makeTemplateObject(cooked: string[], raw: string[]): TemplateStringsArray {
+  Object.defineProperty(cooked, 'raw', {value: raw});
+  return cooked as any;
+}