Translation Files

/**
 * Serializes messages to simple JSON format.
 * Creates key-value mapping of message ID to translated text.
 */
class SimpleJsonTranslationSerializer {
  /**
   * Serialize parsed messages to JSON format.
   * 
   * @param messages - Array of parsed messages to serialize
   * @param options - Format options for output customization
   * @returns JSON string with message ID to translation mapping
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

import { SimpleJsonTranslationSerializer } from "@angular/localize/tools";

const serializer = new SimpleJsonTranslationSerializer();
const messages = [
  { id: "123", text: "Hello {$PH}!", /* other properties */ },
  { id: "456", text: "Welcome!", /* other properties */ }
];

const json = serializer.serialize(messages, {});
console.log(json);
// {
//   "123": "Hello {$PH}!",
//   "456": "Welcome!"
// }

/**
 * Serializes messages to XLIFF 1.2 format.
 * Industry standard format for translation memory tools.
 */
class Xliff1TranslationSerializer {
  /**
   * Serialize parsed messages to XLIFF 1.2 XML format.
   * 
   * @param messages - Array of parsed messages to serialize  
   * @param options - Format options including source/target locale
   * @returns XLIFF 1.2 XML string
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

import { Xliff1TranslationSerializer } from "@angular/localize/tools";

const serializer = new Xliff1TranslationSerializer();
const options = {
  sourceLocale: 'en',
  targetLocale: 'es',
  basePath: process.cwd()
};

const xliff = serializer.serialize(messages, options);
// Generates XLIFF 1.2 XML with <trans-unit> elements

/**
 * Serializes messages to XLIFF 2.1 format.
 * Latest XLIFF standard with improved structure and features.
 */
class Xliff2TranslationSerializer {
  /**
   * Serialize parsed messages to XLIFF 2.1 XML format.
   * 
   * @param messages - Array of parsed messages to serialize
   * @param options - Format options including locale settings  
   * @returns XLIFF 2.1 XML string
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

import { Xliff2TranslationSerializer } from "@angular/localize/tools";

const serializer = new Xliff2TranslationSerializer();
const xliff2 = serializer.serialize(messages, {
  sourceLocale: 'en',
  targetLocale: 'fr'
});
// Generates XLIFF 2.1 XML with <unit> elements

/**
 * Serializes messages to ARB (Application Resource Bundle) format.
 * JSON-based format used by Flutter and other internationalization frameworks.
 */
class ArbTranslationSerializer {
  /**
   * Serialize parsed messages to ARB JSON format.
   * 
   * @param messages - Array of parsed messages to serialize
   * @param options - Format options for ARB metadata
   * @returns ARB JSON string with metadata and messages
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

import { ArbTranslationSerializer } from "@angular/localize/tools";

const serializer = new ArbTranslationSerializer();
const arb = serializer.serialize(messages, {
  sourceLocale: 'en'
});
// Generates ARB JSON with @@locale and message entries

/**
 * Serializes messages to XMB (XML Message Bundle) format.
 * XML format used by Google translation tools.
 */
class XmbTranslationSerializer {
  /**
   * Serialize parsed messages to XMB XML format.
   * 
   * @param messages - Array of parsed messages to serialize
   * @param options - Format options for XMB output
   * @returns XMB XML string
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

/**
 * Serializer for migrating legacy message IDs to new format.
 * Helps transition from old Angular i18n message ID computation.
 */
class LegacyMessageIdMigrationSerializer {
  /**
   * Serialize with legacy ID migration mapping.
   * 
   * @param messages - Array of parsed messages with legacy IDs
   * @param options - Migration options and format settings
   * @returns Migration mapping in specified format
   */
  serialize(messages: ParsedMessage[], options: FormatOptions): string;
}

/**
 * Parses simple JSON translation files.
 * Expects key-value mapping of message ID to translation.
 */
class SimpleJsonTranslationParser {
  /**
   * Parse JSON translation file content.
   * 
   * @param contents - JSON file contents as string
   * @param filePath - Path to file for error reporting
   * @returns Array of parsed translation objects
   */
  parse(contents: string, filePath: string): ParsedTranslation[];
}

import { SimpleJsonTranslationParser } from "@angular/localize/tools";

const parser = new SimpleJsonTranslationParser();
const jsonContent = '{"123": "Hola {$PH}!", "456": "¡Bienvenido!"}';

const translations = parser.parse(jsonContent, 'es.json');
// Returns array of ParsedTranslation objects

/**
 * Parses XLIFF 1.2 translation files.
 * Extracts translations from <trans-unit> elements.
 */
class Xliff1TranslationParser {
  /**
   * Parse XLIFF 1.2 file content.
   * 
   * @param contents - XLIFF XML contents as string
   * @param filePath - Path to file for error reporting
   * @returns Array of parsed translation objects
   */
  parse(contents: string, filePath: string): ParsedTranslation[];
}

/**
 * Parses XLIFF 2.1 translation files.
 * Extracts translations from <unit> elements.
 */
class Xliff2TranslationParser {
  /**
   * Parse XLIFF 2.1 file content.
   * 
   * @param contents - XLIFF 2.1 XML contents as string
   * @param filePath - Path to file for error reporting
   * @returns Array of parsed translation objects
   */
  parse(contents: string, filePath: string): ParsedTranslation[];
}

/**
 * Parses ARB translation files.
 * Handles ARB metadata and message entries.
 */
class ArbTranslationParser {
  /**
   * Parse ARB file content.
   * 
   * @param contents - ARB JSON contents as string
   * @param filePath - Path to file for error reporting
   * @returns Array of parsed translation objects
   */
  parse(contents: string, filePath: string): ParsedTranslation[];
}

/**
 * Parses XTB translation files.
 * Companion format to XMB for translated messages.
 */
class XtbTranslationParser {
  /**
   * Parse XTB file content.
   * 
   * @param contents - XTB XML contents as string
   * @param filePath - Path to file for error reporting
   * @returns Array of parsed translation objects
   */
  parse(contents: string, filePath: string): ParsedTranslation[];
}

/**
 * Options for configuring translation file format output.
 * Different formats support different option subsets.
 */
interface FormatOptions {
  /** Source locale identifier (e.g., 'en', 'en-US') */
  sourceLocale?: string;
  
  /** Target locale identifier for translation */
  targetLocale?: string;
  
  /** Base path for resolving relative file paths */
  basePath?: string;
  
  /** Whether to include source text in output */
  includeContext?: boolean;
  
  /** Custom format-specific options */
  [key: string]: any;
}

// XLIFF options
const xliffOptions: FormatOptions = {
  sourceLocale: 'en-US',
  targetLocale: 'es-ES',
  basePath: process.cwd(),
  includeContext: true
};

// JSON options
const jsonOptions: FormatOptions = {
  sourceLocale: 'en',
  basePath: './src'
};

// ARB options  
const arbOptions: FormatOptions = {
  sourceLocale: 'en',
  includeMetadata: true
};

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

// Extract messages from source files
const extractor = new MessageExtractor();
const messages = extractor.extractMessages(['src/**/*.ts'], {
  basePath: process.cwd()
});

// Serialize to multiple formats
const jsonSerializer = new SimpleJsonTranslationSerializer();
const xliffSerializer = new Xliff1TranslationSerializer();

const jsonOutput = jsonSerializer.serialize(messages, {
  sourceLocale: 'en'
});

const xliffOutput = xliffSerializer.serialize(messages, {
  sourceLocale: 'en',
  targetLocale: 'es'
});

// Write to files
fs.writeFileSync('messages.json', jsonOutput);
fs.writeFileSync('messages.xlf', xliffOutput);

import { 
  SimpleJsonTranslationParser,
  loadTranslations 
} from "@angular/localize/tools";
import "@angular/localize/init";

// Read and parse translations
const jsonContent = fs.readFileSync('es.json', 'utf8');
const parser = new SimpleJsonTranslationParser();
const translations = parser.parse(jsonContent, 'es.json');

// Convert to runtime format
const translationMap: Record<string, string> = {};
translations.forEach(translation => {
  translationMap[translation.id] = translation.text;
});

// Load for runtime use
loadTranslations(translationMap);

// Now $localize calls will use loaded translations
console.log($localize`Hello, World!`); // "¡Hola, Mundo!"