@angular/localize 15.0.0-next.6 → 15.0.0-rc.1

package/src/utils/src/constants.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright Google LLC 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
+ */
+/// <amd-module name="@angular/localize/src/utils/src/constants" />
+/**
+ * The character used to mark the start and end of a "block" in a `$localize` tagged string.
+ * A block can indicate metadata about the message or specify a name of a placeholder for a
+ * substitution expressions.
+ *
+ * For example:
+ *
+ * ```ts
+ * $localize`Hello, ${title}:title:!`;
+ * $localize`:meaning|description@@id:source message text`;
+ * ```
+ */
+export declare const BLOCK_MARKER = ":";
+/**
+ * The marker used to separate a message's "meaning" from its "description" in a metadata block.
+ *
+ * For example:
+ *
+ * ```ts
+ * $localize `:correct|Indicates that the user got the answer correct: Right!`;
+ * $localize `:movement|Button label for moving to the right: Right!`;
+ * ```
+ */
+export declare const MEANING_SEPARATOR = "|";
+/**
+ * The marker used to separate a message's custom "id" from its "description" in a metadata block.
+ *
+ * For example:
+ *
+ * ```ts
+ * $localize `:A welcome message on the home page@@myApp-homepage-welcome: Welcome!`;
+ * ```
+ */
+export declare const ID_SEPARATOR = "@@";
+/**
+ * The marker used to separate legacy message ids from the rest of a metadata block.
+ *
+ * For example:
+ *
+ * ```ts
+ * $localize `:@@custom-id␟2df64767cd895a8fabe3e18b94b5b6b6f9e2e3f0: Welcome!`;
+ * ```
+ *
+ * Note that this character is the "symbol for the unit separator" (␟) not the "unit separator
+ * character" itself, since that has no visual representation. See https://graphemica.com/%E2%90%9F.
+ *
+ * Here is some background for the original "unit separator character":
+ * https://stackoverflow.com/questions/8695118/whats-the-file-group-record-unit-separator-control-characters-and-its-usage
+ */
+export declare const LEGACY_ID_INDICATOR = "\u241F";

package/src/utils/src/messages.d.ts

@@ -0,0 +1,240 @@
+/// <amd-module name="@angular/localize/src/utils/src/messages" />
+/**
+ * Re-export this helper function so that users of `@angular/localize` don't need to actively import
+ * from `@angular/compiler`.
+ */
+export { computeMsgId } from '@angular/compiler';
+/**
+ * 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 declare type SourceMessage = string;
+/**
+ * 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 declare type TargetMessage = string;
+/**
+ * A string that uniquely identifies a message, to be used for matching translations.
+ */
+export declare type MessageId = string;
+/**
+ * Declares a copy of the `AbsoluteFsPath` branded type in `@angular/compiler-cli` to avoid an
+ * import into `@angular/compiler-cli`. The compiler-cli's declaration files are not necessarily
+ * compatible with web environments that use `@angular/localize`, and would inadvertently include
+ * `typescript` declaration files in any compilation unit that uses `@angular/localize` (which
+ * increases parsing time and memory usage during builds) using a default import that only
+ * type-checks when `allowSyntheticDefaultImports` is enabled.
+ *
+ * @see https://github.com/angular/angular/issues/45179
+ */
+declare type AbsoluteFsPathLocalizeCopy = string & {
+    _brand: 'AbsoluteFsPath';
+};
+/**
+ * The location of the message in the source file.
+ *
+ * The `line` and `column` values for the `start` and `end` properties are zero-based.
+ */
+export interface SourceLocation {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+    file: AbsoluteFsPathLocalizeCopy;
+    text?: string;
+}
+/**
+ * Additional information that can be associated with a message.
+ */
+export interface MessageMetadata {
+    /**
+     * A human readable rendering of the message
+     */
+    text: string;
+    /**
+     * Legacy message ids, if provided.
+     *
+     * In legacy message formats the message id can only be computed directly from the original
+     * template source.
+     *
+     * Since this information is not available in `$localize` calls, the legacy message ids may be
+     * attached by the compiler to the `$localize` metablock so it can be used if needed at the point
+     * of translation if the translations are encoded using the legacy message id.
+     */
+    legacyIds?: string[];
+    /**
+     * The id of the `message` if a custom one was specified explicitly.
+     *
+     * This id overrides any computed or legacy ids.
+     */
+    customId?: string;
+    /**
+     * The meaning of the `message`, used to distinguish identical `messageString`s.
+     */
+    meaning?: string;
+    /**
+     * The description of the `message`, used to aid translation.
+     */
+    description?: string;
+    /**
+     * The location of the message in the source.
+     */
+    location?: SourceLocation;
+}
+/**
+ * Information parsed from a `$localize` tagged string that is used to translate it.
+ *
+ * For example:
+ *
+ * ```
+ * const name = 'Jo Bloggs';
+ * $localize`Hello ${name}:title@@ID:!`;
+ * ```
+ *
+ * May be parsed into:
+ *
+ * ```
+ * {
+ *   id: '6998194507597730591',
+ *   substitutions: { title: 'Jo Bloggs' },
+ *   messageString: 'Hello {$title}!',
+ *   placeholderNames: ['title'],
+ *   associatedMessageIds: { title: 'ID' },
+ * }
+ * ```
+ */
+export interface ParsedMessage extends MessageMetadata {
+    /**
+     * The key used to look up the appropriate translation target.
+     */
+    id: MessageId;
+    /**
+     * A mapping of placeholder names to substitution values.
+     */
+    substitutions: Record<string, any>;
+    /**
+     * An optional mapping of placeholder names to associated MessageIds.
+     * This can be used to match ICU placeholders to the message that contains the ICU.
+     */
+    associatedMessageIds?: Record<string, MessageId>;
+    /**
+     * An optional mapping of placeholder names to source locations
+     */
+    substitutionLocations?: Record<string, SourceLocation | undefined>;
+    /**
+     * The static parts of the message.
+     */
+    messageParts: string[];
+    /**
+     * An optional mapping of message parts to source locations
+     */
+    messagePartLocations?: (SourceLocation | undefined)[];
+    /**
+     * The names of the placeholders that will be replaced with substitutions.
+     */
+    placeholderNames: string[];
+}
+/**
+ * Parse a `$localize` tagged string into a structure that can be used for translation or
+ * extraction.
+ *
+ * See `ParsedMessage` for an example.
+ */
+export declare function parseMessage(messageParts: TemplateStringsArray, expressions?: readonly any[], location?: SourceLocation, messagePartLocations?: (SourceLocation | undefined)[], expressionLocations?: (SourceLocation | undefined)[]): ParsedMessage;
+/**
+ * Parse the given message part (`cooked` + `raw`) to extract the message metadata from the text.
+ *
+ * If the message part has a metadata block this function will extract the `meaning`,
+ * `description`, `customId` and `legacyId` (if provided) from the block. These metadata properties
+ * are serialized in the string delimited by `|`, `@@` and `␟` respectively.
+ *
+ * (Note that `␟` is the `LEGACY_ID_INDICATOR` - see `constants.ts`.)
+ *
+ * For example:
+ *
+ * ```ts
+ * `:meaning|description@@custom-id:`
+ * `:meaning|@@custom-id:`
+ * `:meaning|description:`
+ * `:description@@custom-id:`
+ * `:meaning|:`
+ * `:description:`
+ * `:@@custom-id:`
+ * `:meaning|description@@custom-id␟legacy-id-1␟legacy-id-2:`
+ * ```
+ *
+ * @param cooked The cooked version of the message part to parse.
+ * @param raw The raw version of the message part to parse.
+ * @returns A object containing any metadata that was parsed from the message part.
+ */
+export declare function parseMetadata(cooked: string, raw: string): MessageMetadata;
+/**
+ * Parse the given message part (`cooked` + `raw`) to extract any placeholder metadata from the
+ * text.
+ *
+ * If the message part has a metadata block this function will extract the `placeholderName` and
+ * `associatedMessageId` (if provided) from the block.
+ *
+ * These metadata properties are serialized in the string delimited by `@@`.
+ *
+ * For example:
+ *
+ * ```ts
+ * `:placeholder-name@@associated-id:`
+ * ```
+ *
+ * @param cooked The cooked version of the message part to parse.
+ * @param raw The raw version of the message part to parse.
+ * @returns A object containing the metadata (`placeholderName` and `associatedMessageId`) of the
+ *     preceding placeholder, along with the static text that follows.
+ */
+export declare function parsePlaceholder(cooked: string, raw: string): {
+    messagePart: string;
+    placeholderName?: string;
+    associatedMessageId?: string;
+};
+/**
+ * Split a message part (`cooked` + `raw`) into an optional delimited "block" off the front and the
+ * rest of the text of the message part.
+ *
+ * Blocks appear at the start of message parts. They are delimited by a colon `:` character at the
+ * start and end of the block.
+ *
+ * If the block is in the first message part then it will be metadata about the whole message:
+ * meaning, description, id.  Otherwise it will be metadata about the immediately preceding
+ * substitution: placeholder name.
+ *
+ * Since blocks are optional, it is possible that the content of a message block actually starts
+ * with a block marker. In this case the marker must be escaped `\:`.
+ *
+ * @param cooked The cooked version of the message part to parse.
+ * @param raw The raw version of the message part to parse.
+ * @returns An object containing the `text` of the message part and the text of the `block`, if it
+ * exists.
+ * @throws an error if the `block` is unterminated
+ */
+export declare function splitBlock(cooked: string, raw: string): {
+    text: string;
+    block?: string;
+};
+/**
+ * Find the end of a "marked block" indicated by the first non-escaped colon.
+ *
+ * @param cooked The cooked string (where escaped chars have been processed)
+ * @param raw The raw string (where escape sequences are still in place)
+ *
+ * @returns the index of the end of block marker
+ * @throws an error if the block is unterminated
+ */
+export declare function findEndOfBlock(cooked: string, raw: string): number;

package/src/utils/src/translations.d.ts

@@ -0,0 +1,59 @@
+/// <amd-module name="@angular/localize/src/utils/src/translations" />
+import { MessageId, MessageMetadata, ParsedMessage, TargetMessage } from './messages';
+/**
+ * A translation message that has been processed to extract the message parts and placeholders.
+ */
+export interface ParsedTranslation extends MessageMetadata {
+    messageParts: TemplateStringsArray;
+    placeholderNames: string[];
+}
+/**
+ * The internal structure used by the runtime localization to translate messages.
+ */
+export declare type ParsedTranslations = Record<MessageId, ParsedTranslation>;
+export declare class MissingTranslationError extends Error {
+    readonly parsedMessage: ParsedMessage;
+    private readonly type;
+    constructor(parsedMessage: ParsedMessage);
+}
+export declare function isMissingTranslationError(e: any): e is MissingTranslationError;
+/**
+ * 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 `messageId` which is used to find an appropriate
+ * `ParsedTranslation`. If this doesn't match and there are legacy ids then try matching a
+ * translation using those.
+ *
+ * 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 there is no translation with a matching message id then an error is thrown.
+ * If a translation contains a placeholder that is not found in the message being translated then an
+ * error is thrown.
+ */
+export declare function translate(translations: Record<string, ParsedTranslation>, messageParts: TemplateStringsArray, substitutions: readonly any[]): [TemplateStringsArray, readonly any[]];
+/**
+ * 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 declare function parseTranslation(messageString: TargetMessage): ParsedTranslation;
+/**
+ * Create a `ParsedTranslation` from a set of `messageParts` and `placeholderNames`.
+ *
+ * @param messageParts The message parts to appear in the ParsedTranslation.
+ * @param placeholderNames The names of the placeholders to intersperse between the `messageParts`.
+ */
+export declare function makeParsedTranslation(messageParts: string[], placeholderNames?: string[]): ParsedTranslation;
+/**
+ * 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 declare function makeTemplateObject(cooked: string[], raw: string[]): TemplateStringsArray;

package/tools/bundles/{chunk-B2TZRIF5.js → chunk-BWW7SSDP.js}

@@ -15,9 +15,9 @@ import {
   unwrapMessagePartsFromLocalizeCall,
   unwrapMessagePartsFromTemplateLiteral,
   unwrapSubstitutionsFromLocalizeCall
-} from "./chunk-N3C6NOYD.js";
+} from "./chunk-FFZU53GH.js";
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/duplicates.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/duplicates.mjs
 function checkDuplicateMessages(fs, messages, duplicateMessageHandling, basePath) {
   const diagnostics = new Diagnostics();
   if (duplicateMessageHandling === "ignore")
@@ -51,10 +51,10 @@ function serializeMessage(fs, basePath, message) {
   }
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/extraction.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/extraction.mjs
 import { SourceFileLoader } from "@angular/compiler-cli/private/localize";
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/source_files/es2015_extract_plugin.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/source_files/es2015_extract_plugin.mjs
 import { \u0275parseMessage } from "@angular/localize";
 function makeEs2015ExtractPlugin(fs, messages, localizeName = "$localize") {
   return {
@@ -74,7 +74,7 @@ function makeEs2015ExtractPlugin(fs, messages, localizeName = "$localize") {
   };
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/source_files/es5_extract_plugin.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/source_files/es5_extract_plugin.mjs
 import { \u0275parseMessage as \u0275parseMessage2 } from "@angular/localize";
 function makeEs5ExtractPlugin(fs, messages, localizeName = "$localize") {
   return {
@@ -102,7 +102,7 @@ function makeEs5ExtractPlugin(fs, messages, localizeName = "$localize") {
   };
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/extraction.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/extraction.mjs
 var MessageExtractor = class {
   constructor(fs, logger, { basePath, useSourceMaps = true, localizeName = "$localize" }) {
     this.fs = fs;
@@ -169,7 +169,7 @@ var MessageExtractor = class {
   }
 };
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/utils.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/utils.mjs
 function consolidateMessages(messages, getMessageId2) {
   const messageGroups = /* @__PURE__ */ new Map();
   for (const message of messages) {
@@ -210,7 +210,7 @@ function compareLocations({ location: location1 }, { location: location2 }) {
   return 0;
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/arb_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/arb_translation_serializer.mjs
 var ArbTranslationSerializer = class {
   constructor(sourceLocale, basePath, fs) {
     this.sourceLocale = sourceLocale;
@@ -271,7 +271,7 @@ function getMessageId(message) {
   return message.customId || message.id;
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/json_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/json_translation_serializer.mjs
 var SimpleJsonTranslationSerializer = class {
   constructor(sourceLocale) {
     this.sourceLocale = sourceLocale;
@@ -285,7 +285,7 @@ var SimpleJsonTranslationSerializer = class {
   }
 };
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/legacy_message_id_migration_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/legacy_message_id_migration_serializer.mjs
 var LegacyMessageIdMigrationSerializer = class {
   constructor(_diagnostics) {
     this._diagnostics = _diagnostics;
@@ -314,7 +314,7 @@ function shouldMigrate(message) {
   return !message.customId && !!message.legacyIds && message.legacyIds.length > 0;
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/format_options.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/format_options.mjs
 function validateOptions(name, validOptions, options) {
   const validOptionsMap = new Map(validOptions);
   for (const option in options) {
@@ -334,10 +334,10 @@ function parseFormatOptions(optionString = "{}") {
   return JSON.parse(optionString);
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff1_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff1_translation_serializer.mjs
 import { getFileSystem } from "@angular/compiler-cli/private/localize";
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/icu_parsing.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/icu_parsing.mjs
 function extractIcuPlaceholders(text) {
   const state = new StateStack();
   const pieces = new IcuPieces();
@@ -434,7 +434,7 @@ function assert(test, message) {
   }
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xml_file.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xml_file.mjs
 var XmlFile = class {
   constructor() {
     this.output = '<?xml version="1.0" encoding="UTF-8" ?>\n';
@@ -516,7 +516,7 @@ function escapeXml(text) {
   return _ESCAPED_CHARS.reduce((text2, entry) => text2.replace(entry[0], entry[1]), text);
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff1_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff1_translation_serializer.mjs
 var LEGACY_XLIFF_MESSAGE_LENGTH = 40;
 var Xliff1TranslationSerializer = class {
   constructor(sourceLocale, basePath, useLegacyIds, formatOptions = {}, fs = getFileSystem()) {
@@ -664,7 +664,7 @@ var TAG_MAP = {
   "UNORDERED_LIST": "ul"
 };
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff2_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xliff2_translation_serializer.mjs
 import { getFileSystem as getFileSystem2 } from "@angular/compiler-cli/private/localize";
 var MAX_LEGACY_XLIFF_2_MESSAGE_LENGTH = 20;
 var Xliff2TranslationSerializer = class {
@@ -806,7 +806,7 @@ function getTypeForPlaceholder(placeholder) {
   }
 }
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xmb_translation_serializer.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/extract/translation_files/xmb_translation_serializer.mjs
 import { getFileSystem as getFileSystem3 } from "@angular/compiler-cli/private/localize";
 var XmbTranslationSerializer = class {
   constructor(basePath, useLegacyIds, fs = getFileSystem3()) {
@@ -899,4 +899,4 @@ export {
  * 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
  */
-//# sourceMappingURL=chunk-B2TZRIF5.js.map
+//# sourceMappingURL=chunk-BWW7SSDP.js.map

package/tools/bundles/{chunk-N3C6NOYD.js → chunk-FFZU53GH.js}

@@ -2,7 +2,7 @@
       import {createRequire as __cjsCompatRequire} from 'module';
       const require = __cjsCompatRequire(import.meta.url);
     
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/diagnostics.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/diagnostics.mjs
 var Diagnostics = class {
   constructor() {
     this.messages = [];
@@ -37,11 +37,11 @@ var Diagnostics = class {
   }
 };
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/source_file_utils.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/source_file_utils.mjs
 import { getFileSystem } from "@angular/compiler-cli/private/localize";
 import { \u0275isMissingTranslationError, \u0275makeTemplateObject, \u0275translate } from "@angular/localize";
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/babel_core.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/babel_core.mjs
 import * as _babelNamespace from "@babel/core";
 import _babelDefault from "@babel/core";
 var _a;
@@ -56,7 +56,7 @@ var transformSync = babel.transformSync;
 var parseSync = babel.parseSync;
 var transformFromAstSync = babel.transformFromAstSync;
 
-// bazel-out/k8-fastbuild/bin/packages/localize/tools/src/source_file_utils.mjs
+// bazel-out/darwin_arm64-fastbuild/bin/packages/localize/tools/src/source_file_utils.mjs
 function isLocalize(expression, localizeName) {
   return isNamedIdentifier(expression, localizeName) && isGlobalIdentifier(expression);
 }
@@ -340,4 +340,4 @@ export {
  * 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
  */
-//# sourceMappingURL=chunk-N3C6NOYD.js.map
+//# sourceMappingURL=chunk-FFZU53GH.js.map