or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-extraction.mdindex.mdmessage-bundle.mdserializers.mdtranslation-service.md
tile.json

tessl/npm-ngx-translate--i18n-polyfill

A speculative polyfill to support i18n code translations in Angular

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ngx-translate/i18n-polyfill@1.0.x

To install, run

npx @tessl/cli install tessl/npm-ngx-translate--i18n-polyfill@1.0.0

index.mddocs/

@ngx-translate/i18n-polyfill

@ngx-translate/i18n-polyfill is a speculative polyfill that provides comprehensive i18n code translation support for Angular applications. It bridges the gap until native Angular i18n code translation support is available, offering both runtime translation services and powerful CLI extraction tools with support for multiple translation formats.

Package Information

  • Package Name: @ngx-translate/i18n-polyfill
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ngx-translate/i18n-polyfill

Core Imports

// Runtime translation service
import { I18n, I18nDef, MISSING_TRANSLATION_STRATEGY } from "@ngx-translate/i18n-polyfill";

// CLI extraction tools
import { getAst, getFileContent, MessageBundle } from "@ngx-translate/i18n-polyfill/extractor";

// Serializers for different formats
import { xliffWrite, xliff2Write, xmbWrite } from "@ngx-translate/i18n-polyfill/serializers";

// Parser utilities
import { HtmlParser, TranslationBundle } from "@ngx-translate/i18n-polyfill/parser";

For CommonJS:

const { I18n, I18nDef, MISSING_TRANSLATION_STRATEGY } = require("@ngx-translate/i18n-polyfill");
const { getAst, getFileContent } = require("@ngx-translate/i18n-polyfill/extractor");

Basic Usage

import { I18n, I18nDef } from "@ngx-translate/i18n-polyfill";
import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from "@angular/core";

// Configure providers in your Angular module
@NgModule({
  providers: [
    I18n,
    { provide: TRANSLATIONS, useValue: translationsContent },
    { provide: TRANSLATIONS_FORMAT, useValue: "xlf" },
    { provide: LOCALE_ID, useValue: "en" }
  ]
})
export class AppModule {}

// Use in components or services
@Component({...})
export class MyComponent {
  constructor(private i18n: I18n) {}

  translate() {
    // Simple string translation
    const hello = this.i18n("Hello world");
    
    // Translation with interpolation
    const greeting = this.i18n("Hello {{name}}", { name: "John" });
    
    // Translation with metadata
    const message = this.i18n({
      value: "Hello {{name}}",
      id: "greeting.hello",
      meaning: "A friendly greeting",
      description: "Greeting message shown to users"
    }, { name: "John" });
  }
}

Architecture

@ngx-translate/i18n-polyfill is built around several key components:

  • Runtime Translation Service: Injectable Angular service (I18n) for synchronous code-based translations
  • CLI Extraction Tools: Command-line utilities for extracting translatable strings from TypeScript source code
  • Multi-Format Support: Serializers for XLIFF, XLIFF2, XMB, and XTB translation file formats
  • AST Processing: Advanced Abstract Syntax Tree parsing for accurate string extraction
  • Translation Bundle Management: Efficient loading and processing of translation files at runtime

Capabilities

Translation Runtime Service

Injectable Angular service providing synchronous code-based translations with support for interpolations and ICU expressions.

@Injectable()
class I18n {
  constructor(
    format: string,
    translations: string,
    locale: string,
    missingTranslationStrategy?: MissingTranslationStrategy
  );
  
  (def: string | I18nDef, params?: {[key: string]: any}): string;
}

Translation Service

CLI String Extraction

Command-line tools and programmatic APIs for extracting translatable strings from TypeScript source code.

function main(args: string[]): number;
function getAst(paths: string[]): {[url: string]: (string | I18nDef)[]};
function getFileContent(
  messages: {[url: string]: (string | I18nDef)[]},
  sourcePath: string,
  format?: string,
  locale?: string
): string;

CLI Extraction Tools

Translation File Serializers

Serializers for multiple translation file formats including XLIFF, XLIFF2, XMB, and XTB.

function xliffWrite(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;
function xliff2Write(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;
function xmbWrite(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;

Serializers

Message Bundle Management

Manages i18n message collections with support for template processing and message extraction.

class MessageBundle {
  constructor(locale?: string | null);
  updateFromTemplate(template: string | I18nDef, url: string): i18n.Message[];
  getMessages(): i18n.Message[];
  write(write, digest, xmlMessagesById?, createMapper?, filterSources?): string;
}

Message Bundle

Types

interface I18nDef {
  /** The translatable text content */
  value: string;
  /** Optional unique identifier for the message */
  id?: string;
  /** Optional meaning/context for translators */
  meaning?: string;
  /** Optional description for translators */
  description?: string;
}

interface I18n {
  (def: string | I18nDef, params?: {[key: string]: any}): string;
}

interface I18nMessagesById {
  [msgId: string]: string;
}

interface XmlMessagesById {
  [id: string]: xml.Node;
}

interface PlaceholderMapper {
  toPublicName(internalName: string): string | null;
  toInternalName(publicName: string): string | null;
}

interface MessageMetadata {
  meaning?: string;
  description?: string;
  id?: string;
}

const MISSING_TRANSLATION_STRATEGY: InjectionToken<MissingTranslationStrategy>;

Supported Translation Formats

  • XLIFF (.xlf) - Default XML Localization Interchange File Format
  • XLIFF 2.0 (.xlf2) - Updated XLIFF specification
  • XTB - Chrome extension translation format
  • XMB - Angular message bundle format

Angular Integration

The I18n service integrates with Angular's dependency injection system and requires several providers:

import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID, MissingTranslationStrategy } from "@angular/core";
import { I18n, MISSING_TRANSLATION_STRATEGY } from "@ngx-translate/i18n-polyfill";

@NgModule({
  providers: [
    I18n,
    { provide: TRANSLATIONS, useValue: translationFileContent },
    { provide: TRANSLATIONS_FORMAT, useValue: "xlf" },
    { provide: LOCALE_ID, useValue: "en" },
    { provide: MISSING_TRANSLATION_STRATEGY, useValue: MissingTranslationStrategy.Warning }
  ]
})
export class AppModule {}

The service supports interpolation with named parameters and ICU expressions for advanced pluralization and selection scenarios, matching the functionality available in Angular template translations.