@angular/localize

Variables

• ɵ$localize

Functions

• clearTranslations()
• loadTranslations()
• ɵcomputeMsgId()
• ɵfindEndOfBlock()
• ɵisMissingTranslationError()
• ɵmakeParsedTranslation()
• ɵmakeTemplateObject()
• ɵparseMessage()
• ɵparseMetadata()
• ɵparseTranslation()
• ɵsplitBlock()
• ɵtranslate()

Classes

• ɵMissingTranslationError

  • parsedMessage

Interfaces

• ɵLocalizeFn

  • locale
  • translate
• ɵParsedMessage

  • associatedMessageIds
  • id
  • messagePartLocations
  • messageParts
  • placeholderNames
  • substitutionLocations
  • substitutions
• ɵParsedTranslation

  • messageParts
  • placeholderNames
• ɵSourceLocation

  • end
  • file
  • start
  • text
• ɵTranslateFn

Type Aliases

• MessageId
• ɵParsedTranslations
• ɵSourceMessage
• TargetMessage

Namespaces

• global

  • $localize

variable ɵ$localize

const ɵ$localize: ɵLocalizeFn;

• Tag a template literal string for localization.

  For example:

  $localize `some string to localize`

  **Providing meaning, description and id**

  You can optionally specify one or more of meaning, description and id for a localized string by pre-pending it with a colon delimited block of the form:

  $localize`:meaning|description@@id:source message text`;
  
  $localize`:meaning|:source message text`;
  $localize`:description:source message text`;
  $localize`:@@id:source message text`;

  This format is the same as that used for i18n markers in Angular templates. See the [Angular i18n guide](guide/i18n-common-prepare#mark-text-in-component-template).

  **Naming placeholders**

  If the template literal string contains expressions, then the expressions will be automatically associated with placeholder names for you.

  For example:

  $localize `Hi ${name}! There are ${items.length} items.`;

  will generate a message-source of Hi {$PH}! There are {$PH_1} items.

  The recommended practice is to name the placeholder associated with each expression though.

  Do this by providing the placeholder name wrapped in : characters directly after the expression. These placeholder names are stripped out of the rendered localized string.

  For example, to name the items.length expression placeholder itemCount you write:

  $localize `There are ${items.length}:itemCount: items`;

  **Escaping colon markers**

  If you need to use a : character directly at the start of a tagged string that has no metadata block, or directly after a substitution expression that has no name you must escape the : by preceding it with a backslash:

  For example:

  // message has a metadata block so no need to escape colon
  $localize `:some description::this message starts with a colon (:)`;
  // no metadata block so the colon must be escaped
  $localize `\:this message starts with a colon (:)`;

  // named substitution so no need to escape colon
  $localize `${label}:label:: ${}`
  // anonymous substitution so colon must be escaped
  $localize `${label}\: ${}`

  **Processing localized strings:**

  There are three scenarios:

  * **compile-time inlining**: the $localize tag is transformed at compile time by a transpiler, removing the tag and replacing the template literal string with a translated literal string from a collection of translations provided to the transpilation tool.

  * **run-time evaluation**: the $localize tag is a run-time function that replaces and reorders the parts (static strings and expressions) of the template literal string with strings from a collection of translations loaded at run-time.

  * **pass-through evaluation**: the $localize tag is a run-time function that simply evaluates the original template literal string without applying any translations to the parts. This version is used during development or where there is no need to translate the localized template literals.

  Parameter messageParts

  a collection of the static parts of the template string.

  Parameter expressions

  a collection of the values of each placeholder in the template string.

  Returns

  the translated string, with the messageParts and expressions interleaved together.

function clearTranslations

clearTranslations: () => void;

• Remove all translations for $localize, if doing runtime translation.

  All translations that had been loading into memory using loadTranslations() will be removed.

  See Also

  • loadTranslations for loading translations at runtime.

  • for tagging messages as needing to be translated.

function loadTranslations

loadTranslations: (translations: Record<MessageId, TargetMessage>) => void;

• Load translations for use by $localize, if doing runtime translation.

  If the $localize tagged strings are not going to be replaced at compiled time, it is possible to load a set of translations that will be applied to the $localize tagged strings at runtime, in the browser.

  Loading a new translation will overwrite a previous translation if it has the same MessageId.

  Note that $localize messages are only processed once, when the tagged string is first encountered, and does not provide dynamic language changing without refreshing the browser. Loading new translations later in the application life-cycle will not change the translated text of messages that have already been translated.

  The message IDs and translations are in the same format as that rendered to "simple JSON" translation files when extracting messages. In particular, placeholders in messages are rendered using the {$PLACEHOLDER_NAME} syntax. For example the message from the following template:

  <div i18n>pre<span>inner-pre<b>bold</b>inner-post</span>post</div>

  would have the following form in the translations map:

  {
    "2932901491976224757":
       "pre{$START_TAG_SPAN}inner-pre{$START_BOLD_TEXT}bold{$CLOSE_BOLD_TEXT}inner-post{$CLOSE_TAG_SPAN}post"
  }

  Parameter translations

  A map from message ID to translated message.

  These messages are processed and added to a lookup based on their MessageId.

  See Also

  • clearTranslations for removing translations loaded using this function.

  • for tagging messages as needing to be translated.

function ɵcomputeMsgId

ɵcomputeMsgId: (msg: string, meaning?: string) => string;

function ɵfindEndOfBlock

ɵfindEndOfBlock: (cooked: string, raw: string) => number;

• Find the end of a "marked block" indicated by the first non-escaped colon.

  Parameter cooked

  The cooked string (where escaped chars have been processed)

  Parameter 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

function ɵisMissingTranslationError

ɵisMissingTranslationError: (e: any) => e is ɵMissingTranslationError;

function ɵmakeParsedTranslation

ɵmakeParsedTranslation: (
    messageParts: string[],
    placeholderNames?: string[]
) => ɵParsedTranslation;

• Create a ParsedTranslation from a set of messageParts and placeholderNames.

  Parameter messageParts

  The message parts to appear in the ParsedTranslation.

  Parameter placeholderNames

  The names of the placeholders to intersperse between the messageParts.

function ɵmakeTemplateObject

ɵmakeTemplateObject: (cooked: string[], raw: string[]) => TemplateStringsArray;

• Create the specialized array that is passed to tagged-string tag functions.

  Parameter cooked

  The message parts with their escape codes processed.

  Parameter raw

  The message parts with their escaped codes as-is.

function ɵparseMessage

ɵparseMessage: (
    messageParts: TemplateStringsArray,
    expressions?: readonly any[],
    location?: ɵSourceLocation,
    messagePartLocations?: (ɵSourceLocation | undefined)[],
    expressionLocations?: (ɵSourceLocation | undefined)[]
) => ɵParsedMessage;

• Parse a $localize tagged string into a structure that can be used for translation or extraction.

  See ParsedMessage for an example.

function ɵparseMetadata

ɵparseMetadata: (cooked: string, raw: string) => MessageMetadata;

• 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:

  `: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:`

  Parameter cooked

  The cooked version of the message part to parse.

  Parameter raw

  The raw version of the message part to parse.

  Returns

  A object containing any metadata that was parsed from the message part.

function ɵparseTranslation

ɵparseTranslation: (messageString: TargetMessage) => ɵParsedTranslation;

• 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.

  Parameter message

  the message to be parsed.

function ɵsplitBlock

ɵsplitBlock: (cooked: string, raw: string) => { text: string; block?: 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 \:.

  Parameter cooked

  The cooked version of the message part to parse.

  Parameter 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

function ɵtranslate

ɵtranslate: (
    translations: Record<string, ɵParsedTranslation>,
    messageParts: TemplateStringsArray,
    substitutions: readonly any[]
) => [TemplateStringsArray, readonly any[]];

• 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.

type MessageId

type MessageId = string;

• A string that uniquely identifies a message, to be used for matching translations.

type ɵParsedTranslations

type ɵParsedTranslations = Record<MessageId, ɵParsedTranslation>;

• The internal structure used by the runtime localization to translate messages.

type ɵSourceMessage

type ɵSourceMessage = string;

• 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.

type TargetMessage

type TargetMessage = 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.