CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-formatjs--cli

A comprehensive CLI for internationalization workflows with message extraction, compilation, and verification capabilities.

—

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

compilation.mddocs/

Message Compilation

Compile extracted translation files into formats consumable by react-intl, with support for AST compilation, pseudo-locale generation, and various output formats.

Capabilities

Compile Function

Compiles translation files and returns the compiled data.

/**
 * Compile translation files into consumable format
 * @param files - Array of translation file paths
 * @param opts - Compilation options
 * @returns Promise resolving to serialized JSON string
 */
function compile(files: string[], opts: CompileOpts): Promise<string>;

interface CompileOpts {
  /** Whether to compile message into AST instead of just string */
  ast?: boolean;
  /** Whether to continue compiling after encountering an error */
  skipErrors?: boolean;
  /** Path to a formatter file or Formatter object */
  format?: string | Formatter<unknown>;
  /** Whether to compile to pseudo locale */
  pseudoLocale?: PseudoLocale;
  /** Whether to treat HTML/XML tags as string literal */
  ignoreTag?: boolean;
}

Compile and Write Function

Compiles translation files and writes them directly to output files.

/**
 * Compile translation files and write to output
 * @param files - Array of translation file paths
 * @param opts - CLI compilation options
 */
function compileAndWrite(files: string[], opts: CompileCLIOpts): Promise<void>;

interface CompileCLIOpts extends CompileOpts {
  /** The target file that contains compiled messages */
  outFile?: string;
}

Pseudo Locale Types

type PseudoLocale = 'xx-LS' | 'xx-AC' | 'xx-HA' | 'en-XA' | 'en-XB';

Note: Pseudo locale generation functions are internal and not exported for programmatic use. Use the --pseudo-locale CLI option instead.

Usage Examples

Basic Compilation

import { compile } from "@formatjs/cli-lib";

// Compile to string format (default)
const compiled = await compile(['translations/en.json'], {
  skipErrors: false
});

// Compile to AST format for better runtime performance
const astCompiled = await compile(['translations/en.json'], {
  ast: true
});

Compilation with Custom Formatter

import { compileAndWrite } from "@formatjs/cli-lib";

// Use built-in formatter
await compileAndWrite(['translations/crowdin-en.json'], {
  format: 'crowdin',
  outFile: 'compiled/en.json',
  ast: true
});

// Use custom formatter
await compileAndWrite(['translations/custom-en.json'], {
  format: './formatters/my-formatter.js',
  outFile: 'compiled/en.json'
});

Pseudo Locale Generation

import { compile } from "@formatjs/cli-lib";

// Generate pseudo locale for testing
const pseudoCompiled = await compile(['translations/en.json'], {
  pseudoLocale: 'xx-LS', // Longer strings
  ast: true
});

// Different pseudo locales for different testing needs
const accentedPseudo = await compile(['translations/en.json'], {
  pseudoLocale: 'xx-AC' // Accented characters
});

const rtlPseudo = await compile(['translations/en.json'], {
  pseudoLocale: 'en-XA' // RTL simulation
});

Error Handling in Compilation

import { compile } from "@formatjs/cli-lib";

// Continue compilation despite errors
const partialCompiled = await compile(['translations/broken-en.json'], {
  skipErrors: true, // Don't fail on individual message errors
  ast: true
});

// Strict compilation - fail on any error
try {
  const strictCompiled = await compile(['translations/en.json'], {
    skipErrors: false
  });
} catch (error) {
  console.error('Compilation failed:', error.message);
}

HTML/XML Tag Handling

import { compile } from "@formatjs/cli-lib";

// Treat HTML tags as string literals (safer)
const safeCompiled = await compile(['translations/en.json'], {
  ignoreTag: true,
  ast: true
});

// Parse HTML tags as proper tokens (default)
const richCompiled = await compile(['translations/en.json'], {
  ignoreTag: false
});

CLI Usage

Basic Compilation

# Compile single file
formatjs compile translations/en.json --out-file compiled/en.json

# Compile with AST format
formatjs compile translations/en.json --out-file compiled/en.json --ast

# Compile multiple files with glob
formatjs compile 'translations/*.json' --out-file compiled/all.json

Compilation with Formatters

# Use built-in formatter
formatjs compile translations/crowdin-en.json --format crowdin --out-file compiled/en.json

# Use custom formatter
formatjs compile translations/custom-en.json --format ./my-formatter.js --out-file compiled/en.json

Pseudo Locale Generation

# Generate longer strings pseudo locale
formatjs compile translations/en.json --pseudo-locale xx-LS --ast --out-file compiled/xx-LS.json

# Generate accented characters pseudo locale  
formatjs compile translations/en.json --pseudo-locale xx-AC --ast --out-file compiled/xx-AC.json

# Generate RTL simulation pseudo locale
formatjs compile translations/en.json --pseudo-locale en-XA --ast --out-file compiled/en-XA.json

Batch Folder Compilation

The CLI provides a dedicated command for compiling entire directories of translation files.

/**
 * Compile all JSON files in a folder to an output folder
 * @param folder - Input folder containing JSON translation files
 * @param outFolder - Output folder for compiled files
 * @param --format - Optional formatter to use
 * @param --ast - Compile to AST format
 */
formatjs compile-folder <folder> <outFolder> [options]

Usage Examples:

# Compile entire folder
formatjs compile-folder translations/ compiled/ --ast

# Compile folder with custom formatter
formatjs compile-folder translations/ compiled/ --format smartling --ast

# Compile folder with built-in formatter
formatjs compile-folder translations/ compiled/ --format crowdin

Note: The compile-folder command processes all .json files in the input folder and creates corresponding files in the output folder.

Error Handling Options

# Skip errors and continue compilation
formatjs compile 'translations/*.json' --skip-errors --out-file compiled/partial.json

# Ignore HTML tags (treat as string literals)
formatjs compile translations/en.json --ignore-tag --out-file compiled/en.json

Input File Formats

FormatJS CLI can compile various input formats:

Standard FormatJS Format

{
  "greeting": {
    "id": "greeting",
    "defaultMessage": "Hello {name}!",
    "description": "Greeting message"
  }
}

Simple Key-Value Format

{
  "greeting": "Hello {name}!",
  "farewell": "Goodbye!"
}

TMS-Specific Formats

With appropriate formatters, the CLI can handle formats from:

  • Crowdin
  • Lokalise
  • Smartling
  • Transifex
  • And custom formats via formatter files

Output Formats

String Compilation (Default)

{
  "greeting": "Hello {name}!",
  "farewell": "Goodbye!"
}

AST Compilation

{
  "greeting": [
    {"type": 0, "value": "Hello "},
    {"type": 1, "value": "name"},
    {"type": 0, "value": "!"}
  ],
  "farewell": [
    {"type": 0, "value": "Goodbye!"}
  ]
}

AST compilation provides better runtime performance as messages are pre-parsed.

docs

compilation.md

extraction.md

formatters.md

index.md

verification.md

tile.json