CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-angular--localize

Angular's internationalization library providing $localize tagged template function for translation support

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@angular/localize

@angular/localize is Angular's internationalization (i18n) and localization library that provides the $localize tagged template literal function for marking strings for translation. It enables both compile-time and runtime translation scenarios with zero-runtime-cost static translation through build-time processing.

Package Information

  • Package Name: @angular/localize
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @angular/localize
  • Installation (Angular CLI): ng add @angular/localize

Core Imports

import { loadTranslations, clearTranslations } from "@angular/localize";

For the $localize function (typically imported via polyfill):

import "@angular/localize/init";

For CLI tools:

import { MessageExtractor, translateFiles } from "@angular/localize/tools";

Basic Usage

Marking strings for translation

import "@angular/localize/init";

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

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

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

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

Runtime translation loading

import { loadTranslations, clearTranslations } from "@angular/localize";

// Load translations for runtime usage
loadTranslations({
  "4286451273117902052": "¡Hola, Mundo!",
  "2788806693285683417": "¡Hola, {$PH}!"
});

// Clear all loaded translations
clearTranslations();

Architecture

@angular/localize is built around several key components:

  • $localize Function: Global tagged template function for marking translatable strings
  • Message Processing: Parsing and metadata extraction from tagged strings
  • Translation Runtime: Runtime translation loading and string replacement
  • CLI Tools: Command-line utilities for extraction, translation, and migration
  • Build Integration: Compile-time translation replacement for zero-runtime cost
  • Angular Integration: Seamless integration with Angular templates and CLI

Capabilities

Core Localization

The fundamental $localize tagged template function and runtime translation functionality for marking strings and loading translations at runtime.

const $localize: LocalizeFn;

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

interface TranslateFn {
  (messageParts: TemplateStringsArray, expressions: readonly any[]): [TemplateStringsArray, readonly any[]];
}

Core Localization

Runtime Translation Management

Functions for loading and managing translations at runtime, enabling dynamic language switching and translation loading.

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

type MessageId = string;
type TargetMessage = string;

Runtime Translation

Message Processing & Utilities

Core utilities for parsing, processing, and manipulating localize messages, including metadata extraction and message ID computation.

function parseMessage(
  messageParts: TemplateStringsArray,
  expressions?: readonly any[],
  location?: SourceLocation
): ParsedMessage;

function parseMetadata(cooked: string, raw: string): MessageMetadata;
function computeMsgId(messageString: string, meaning: string): string;

Message Processing

Translation File Handling

Serializers and parsers for various translation file formats including XLIFF, JSON, ARB, and XMB for integration with translation workflows.

class ArbTranslationSerializer {
  serialize(messages: ɵParsedMessage[], options: FormatOptions): string;
}

class Xliff1TranslationSerializer {  
  serialize(messages: ɵParsedMessage[], options: FormatOptions): string;
}

class SimpleJsonTranslationSerializer {
  serialize(messages: ɵParsedMessage[], options: FormatOptions): string;  
}

Translation Files

CLI Tools & Commands

Command-line utilities for message extraction, source file translation, and legacy code migration integrated with the Angular CLI and build processes.

class MessageExtractor {
  extractMessages(
    rootPaths: string[],
    options: ExtractorOptions
  ): ɵParsedMessage[];
}

function extractTranslations(config: ExtractorConfig): void;
function translateFiles(config: TranslateConfig): void;

Binary commands available:

  • localize-extract: Extract translatable messages from source files
  • localize-translate: Translate source files using translation files
  • localize-migrate: Migrate legacy i18n usage to $localize format

CLI Tools

Types

Core Types

interface MessageMetadata {
  text: string;
  meaning?: string;
  description?: string;
  customId?: string;
  legacyIds?: string[];
  location?: SourceLocation;
}

interface ParsedMessage extends MessageMetadata {
  id: MessageId;
  substitutions: Record<string, any>;
  messageParts: string[];
  placeholderNames: string[];
  associatedMessageIds?: Record<string, MessageId>;
}

interface ParsedTranslation extends MessageMetadata {
  messageParts: TemplateStringsArray;
  placeholderNames: string[];
}

interface SourceLocation {
  start: { line: number; column: number };
  end: { line: number; column: number };
  file: string;
  text?: string;
}

Error Types

class MissingTranslationError extends Error {
  constructor(readonly parsedMessage: ParsedMessage);
}

function isMissingTranslationError(e: any): e is MissingTranslationError;

Constants

const BLOCK_MARKER = ':';
const MEANING_SEPARATOR = '|';
const ID_SEPARATOR = '@@';
const LEGACY_ID_INDICATOR = '\u241F';

docs

cli-tools.md

core-localization.md

index.md

message-processing.md

runtime-translation.md

translation-files.md

tile.json