or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tools.mdcore-localization.mdindex.mdmessage-processing.mdruntime-translation.mdtranslation-files.md
tile.json

core-localization.mddocs/

Core Localization

The fundamental $localize tagged template function and related interfaces that form the core of Angular's localization system.

Capabilities

$localize Function

The global tagged template function that marks strings for translation. Can operate in compile-time replacement, runtime translation, or pass-through modes.

/**
 * Tag a template literal string for localization.
 * Supports metadata blocks for meaning, description, and custom IDs.
 * Handles placeholder naming and escaping.
 * 
 * @param messageParts - Collection of static parts of the template string
 * @param expressions - Collection of placeholder values  
 * @returns Translated string with messageParts and expressions interleaved
 */
const $localize: LocalizeFn;

interface LocalizeFn {
  (messageParts: TemplateStringsArray, ...expressions: readonly any[]): string;
  translate?: TranslateFn;
  locale?: string;
}

Usage Examples:

// Simple string marking
const message = $localize`Hello, World!`;

// With placeholders
const greeting = $localize`Hello, ${name}!`;

// With metadata block (meaning|description@@customId)
const title = $localize`:page-title|The main page title@@homepage-title:Welcome to our site`;

// With named placeholders
const status = $localize`There are ${count}:itemCount: items remaining`;

// With only description
const label = $localize`:Button to save changes:Save`;

// With only custom ID
const error = $localize`:@@error-404:Page not found`;

// With meaning only
const action = $localize`:user-action|:Delete`;

// Escaping colon markers
const messageWithColon = $localize`\:This message starts with a colon`;
const substitutionWithColon = $localize`${value}\: followed by colon`;

Translation Function Interface

Interface for the translation function that can be attached to $localize for runtime translation.

/**
 * Function that converts input message with expressions into translated message.
 * May modify arrays in place and reorder expressions for different translations.
 * 
 * @param messageParts - Template string array parts
 * @param expressions - Expression values array
 * @returns Tuple of translated messageParts and reordered expressions
 */
interface TranslateFn {
  (
    messageParts: TemplateStringsArray,
    expressions: readonly any[]
  ): [TemplateStringsArray, readonly any[]];
}

Locale Property

Optional locale identifier that can be set on the $localize function.

/**
 * Current locale of translated messages.
 * Can be replaced at compile-time with string literal by inliner.
 */
$localize.locale?: string;

Usage Example:

// Check current locale (compile-time replaceable)
if (typeof $localize !== "undefined" && $localize.locale) {
  console.log(`Current locale: ${$localize.locale}`);
}

Initialization

Global Registration

To make $localize available globally, import the initialization module:

import "@angular/localize/init";

// $localize is now available globally
const message = $localize`Hello, World!`;

Manual Registration

Alternatively, import and register manually:

import { $localize } from "@angular/localize/init";

// Use directly without global registration
const message = $localize`Hello, World!`;

// Or register globally
(globalThis as any).$localize = $localize;

Metadata Block Format

The $localize function supports rich metadata through colon-delimited blocks:

Format Specification

:meaning|description@@customId:message text
  • meaning: Distinguishes identical message strings in different contexts
  • description: Aids translators with context about the message
  • customId: Custom identifier overriding computed message ID
  • legacyIds: Legacy message IDs (separated by ␟ character)

Examples

// Full metadata
$localize`:user-greeting|Greeting shown to logged in user@@welcome-msg:Welcome, ${name}!`;

// Description only
$localize`:Confirmation dialog title:Are you sure?`;

// Custom ID only  
$localize`:@@btn-cancel:Cancel`;

// Meaning only
$localize`:navigation|:Home`;

// With legacy IDs
$localize`:@@new-id␟legacy-id-1␟legacy-id-2:Message text`;

Placeholder Naming

Automatic Naming

Without explicit names, placeholders get automatic names:

$localize`Hi ${name}! There are ${items.length} items.`;
// Generates: "Hi {$PH}! There are {$PH_1} items."

Explicit Naming

Named placeholders improve translation clarity:

$localize`There are ${items.length}:itemCount: items for ${user.name}:userName:.`;
// Generates: "There are {$itemCount} items for {$userName}."

Escaping

Colons must be escaped when not part of metadata blocks:

// Escaped colon after substitution
$localize`${label}\: value is ${value}`;

// Escaped colon at start (no metadata block)  
$localize`\:This starts with colon`;

Processing Modes

Compile-time Inlining

Build tools replace $localize calls with translated strings:

// Source
$localize`Hello, ${name}!`;

// After compilation (Spanish)
"Hola, " + name + "!";

Runtime Evaluation

$localize.translate function processes messages at runtime:

// With translations loaded
$localize`Hello, World!`; // Returns "Hola, Mundo!"

Pass-through Mode

Development mode that returns original template literal:

// Without translations
$localize`Hello, World!`; // Returns "Hello, World!"