or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compilation.mdextraction.mdformatters.mdindex.mdverification.md
tile.json

index.mddocs/

FormatJS CLI

FormatJS CLI is a comprehensive command-line interface for internationalization (i18n) workflows in JavaScript and React applications. It provides powerful message extraction from source code, compilation of translation files into runtime-consumable formats, and verification tools to ensure translation completeness and consistency.

Package Information

  • Package Name: @formatjs/cli
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install @formatjs/cli
  • Binary: formatjs (via @formatjs/cli wrapper package)

Core Imports

For programmatic usage of the CLI library:

import { extract, extractAndWrite, compile, compileAndWrite } from "@formatjs/cli-lib";
import type { ExtractOpts, CompileOpts, MessageDescriptor } from "@formatjs/cli-lib";

CommonJS:

const { extract, extractAndWrite, compile, compileAndWrite } = require("@formatjs/cli-lib");

Note: The verify function is internal to the CLI and not exported for programmatic use.

Basic Usage

CLI Usage

# Extract messages from source files
formatjs extract 'src/**/*.{js,jsx,ts,tsx}' --out-file messages/extracted.json

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

# Verify translation completeness
formatjs verify 'translations/*.json' --source-locale en --missing-keys

Programmatic Usage

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

// Extract messages and write to file
await extractAndWrite(['src/App.tsx'], {
  outFile: 'messages.json',
  idInterpolationPattern: '[sha512:contenthash:base64:6]'
});

// Compile messages and write to file
await compileAndWrite(['translations/en.json'], {
  outFile: 'compiled/en.json',
  ast: true
});

Architecture

FormatJS CLI is built around several key components:

  • CLI Interface: Command-line wrapper that uses Commander.js for argument parsing and command routing
  • Extraction Engine: TypeScript transformer-based message extraction with support for React components, Vue.js, and Glimmer templates
  • Format System: Pluggable formatter architecture supporting multiple TMS formats (Crowdin, Lokalise, Smartling, etc.)
  • Compilation Engine: ICU MessageFormat parser and compiler for generating runtime-consumable message bundles
  • Verification System: Translation file analysis for missing keys and structural consistency
  • Pseudo Localization: Test locale generation for UI testing and layout validation

Capabilities

Message Extraction

Extract translatable messages from source code files including React components, defineMessages calls, and intl.formatMessage usage with extensive customization options.

function extract(files: readonly string[], opts: ExtractOpts): Promise<string>;
function extractAndWrite(files: readonly string[], opts: ExtractCLIOptions): Promise<void>;

Message Extraction

Message Compilation

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

function compile(files: string[], opts: CompileOpts): Promise<string>;
function compileAndWrite(files: string[], opts: CompileCLIOpts): Promise<void>;

Message Compilation

Translation Verification

Verify translation files for completeness and consistency, checking for missing keys and structural equality between locales. Available only via CLI command.

formatjs verify [translation_files...] --source-locale <locale> [options]

Translation Verification

Format System

Pluggable formatter system for converting between different translation management system formats with built-in support for major TMS providers.

interface Formatter<T> {
  serialize?: SerializeFn<T>;
  format: FormatFn<T>;  
  compile: CompileFn<T>;
  compareMessages?: Comparator;
}

function resolveBuiltinFormatter(format?: string | Formatter<unknown>): Promise<any>;

Format System

Types

interface MessageDescriptor {
  id: string;
  defaultMessage?: string;
  description?: string | object;
  start?: number;
  end?: number;
  file?: string;
}

interface ExtractionResult<M = Record<string, string>> {
  messages: MessageDescriptor[];
  meta?: M;
}

interface ExtractedMessageDescriptor extends MessageDescriptor {
  line?: number;
  col?: number;
  meta?: Record<string, string>;
}

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

interface Formatter<T> {
  serialize?: SerializeFn<T>;
  format: FormatFn<T>;
  compile: CompileFn<T>;
  compareMessages?: Comparator;
}

type FormatFn<T = Record<string, MessageDescriptor>> = (
  msgs: Record<string, MessageDescriptor>
) => T;

type CompileFn<T = Record<string, MessageDescriptor>> = (
  msgs: T
) => Record<string, string>;

type SerializeFn<T = Record<string, MessageDescriptor>> = (
  msgs: T
) => string;

type Comparator = (a: {key: string, value: any}, b: {key: string, value: any}) => number;