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

A speculative polyfill to support i18n code translations in Angular

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

CLI Extraction Tools

Name: tessl/npm-ngx-translate--i18n-polyfill
Author: tessl

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

Capabilities

CLI Main Function

The main entry point for the ngx-extractor command-line tool.

/**
 * Main CLI entry point for the ngx-extractor tool
 * Processes command line arguments and executes string extraction
 * @param args - Command line arguments array
 * @returns Process exit code (0 for success, non-zero for errors)
 */
function main(args: string[]): number;

CLI Usage:

# Extract strings to XLIFF format
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf -f xlf -l en

# Extract strings to XLIFF2 format  
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf2 -f xlf2

# Extract strings to XMB format
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xmb -f xmb

# Multiple input paths
ngx-extractor -i "src/**/*.ts" -i "lib/**/*.ts" -o messages.xlf

CLI Options:

-i, --input - Input file paths to extract strings from (supports glob patterns, can be specified multiple times)
-o, --out-file - Output file path for extracted translation file (required)
-f, --format - Output format: "xlf", "xlf2", or "xmb" (default: "xlf")
-l, --locale - Source language/locale of the application (default: "en")

AST Extraction Function

Core function that extracts translatable strings from TypeScript source files.

/**
 * Extracts translatable strings from TypeScript files by parsing AST
 * Searches for I18n service calls and extracts string literals and I18nDef objects
 * @param paths - Array of file paths to process (supports glob patterns)
 * @returns Object mapping file URLs to arrays of extracted messages
 */
function getAst(paths: string[]): {[url: string]: (string | I18nDef)[]};

Usage Example:

import { getAst } from "@ngx-translate/i18n-polyfill/extractor";

// Extract from specific files
const messages = getAst(["src/app.component.ts", "src/services/user.service.ts"]);

// Extract using glob patterns
const allMessages = getAst(["src/**/*.ts", "lib/**/*.component.ts"]);

// Result structure:
// {
//   "src/app.component.ts": ["Hello world", { value: "Welcome", id: "welcome.msg" }],
//   "src/user.service.ts": ["User not found", "Please try again"]
// }

Translation File Generator

Generates translation file content from extracted messages in various formats.

/**
 * Generates translation file content from extracted messages
 * Supports XLIFF, XLIFF2, and XMB output formats
 * @param messages - Extracted messages by file URL
 * @param sourcePath - Source file path for the translation file
 * @param format - Output format: "xlf", "xlf2", or "xmb" (default: "xlf")
 * @param locale - Source locale for the translation file (default: "en")
 * @returns Generated translation file content as string
 */
function getFileContent(
  messages: {[url: string]: (string | I18nDef)[]},
  sourcePath: string,
  format?: string,
  locale?: string
): string;

Usage Example:

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

// Extract messages from source files
const extractedMessages = getAst(["src/**/*.ts"]);

// Generate XLIFF file content
const xliffContent = getFileContent(
  extractedMessages,
  "src/i18n/messages.xlf",
  "xlf",
  "en"
);

// Generate XLIFF2 file content
const xliff2Content = getFileContent(
  extractedMessages,
  "src/i18n/messages.xlf2", 
  "xlf2",
  "en"
);

// Write to file
require("fs").writeFileSync("messages.xlf", xliffContent);

Extraction Patterns

The extraction tool recognizes several patterns of I18n service usage:

Simple String Calls

// Extracted as: "Hello world"
this.i18n("Hello world");
i18n("Simple message");

Calls with Interpolation

// Extracted as: "Hello {{name}}"
this.i18n("Hello {{name}}", { name: userName });

I18nDef Object Calls

// Extracted as: { value: "Welcome", id: "welcome.msg", meaning: "greeting", description: "Welcome message" }
this.i18n({
  value: "Welcome",
  id: "welcome.msg", 
  meaning: "greeting",
  description: "Welcome message"
});

Template Literals

// Extracted as: "Hello {{name}}, you have {{count}} messages"
const message = `Hello {{name}}, you have {{count}} messages`;
this.i18n(message, { name, count });

Variable References

// Only extracts if the variable value can be statically determined
const WELCOME_MSG = "Welcome to our app";
this.i18n(WELCOME_MSG);

Binary Installation

The CLI tool is available as a binary when the package is installed:

{
  "bin": {
    "ngx-extractor": "extractor/ngx-extractor.js"
  },
  "scripts": {
    "extract": "ngx-extractor -i 'src/**/*.ts' -o src/i18n/messages.xlf"
  }
}

Integration with Angular i18n

The extracted translation files are compatible with Angular's standard i18n workflow:

Extract template messages using Angular CLI:
```
ng extract-i18n --output-path src/i18n
```

Extract code messages using ngx-extractor:

ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf

Translate the merged file and configure Angular for production builds with translated content.

The tool merges extracted code messages with existing translation files, preserving existing translations while adding new messages that need translation.