formatjs_cli

A high-performance Rust-based command-line interface for FormatJS internationalization tools.

Overview

formatjs_cli is a high-performance Rust implementation of the FormatJS CLI, providing fast and efficient tools for working with ICU MessageFormat messages in your internationalization workflow.

Why Use the Native CLI?

The native Rust CLI offers significant advantages over the Node.js-based @formatjs/cli:

• 🚀 Faster Performance: Up to 10-100x faster for large codebases
• 📦 Zero Dependencies: Single binary with no Node.js or npm packages required
• 💾 Lower Memory Usage: Minimal memory footprint compared to Node.js
• ⚡ Instant Startup: No Node.js initialization overhead
• 🔧 Easy Distribution: Standalone binaries for CI/CD pipelines
• 🎯 Perfect for CI/CD: Fast, reliable, and cache-friendly

Benchmark results (processing ~1000 message files):

• Node.js CLI: ~8.5 seconds
• Rust CLI: ~0.5 seconds (17x faster)

The native CLI is a drop-in replacement for @formatjs/cli with identical command-line interface and output format.

Features

• Extract: Extract messages from source files (React, Vue, etc.)
• Compile: Compile messages for production use with optional minification
• Verify: Validate message files and check for missing/extra keys
• Compile-Folder: Batch compile all translation files in a folder

Quick Start

# Download the binary (macOS Apple Silicon example)
curl -L https://github.com/formatjs/formatjs/releases/download/formatjs_cli_v0.1.6/formatjs-darwin-arm64 -o formatjs
chmod +x formatjs

# Extract messages from your source code
./formatjs extract "src/**/*.tsx" --out-file messages.json

# Compile translations for production
./formatjs compile "translations/*.json" --out-file compiled.json --ast

# Verify translations are complete
./formatjs verify "translations/*.json" --source-locale en --missing-keys

Installation

Pre-built Binaries (Recommended)

Download pre-built native binaries from the GitHub Releases page:

Latest Release: formatjs_cli_v0.1.6

Available binaries:

• formatjs-darwin-arm64 - macOS Apple Silicon (M1/M2/M3)
• formatjs-linux-x86_64 - Linux x86_64

Installation steps:

1. Download the appropriate binary for your platform:

   # macOS Apple Silicon
   curl -L https://github.com/formatjs/formatjs/releases/download/formatjs_cli_v0.1.6/formatjs-darwin-arm64 -o formatjs
   
   # Linux x86_64
   curl -L https://github.com/formatjs/formatjs/releases/download/formatjs_cli_v0.1.6/formatjs-linux-x86_64 -o formatjs
   

2. Make it executable:

   chmod +x formatjs
   

3. Optionally, move it to your PATH:

   sudo mv formatjs /usr/local/bin/
   

4. Verify installation:

   formatjs --version
   

Using Bazel

Build the CLI using Bazel for host platform:

bazel build //rust/formatjs_cli:formatjs

Run directly with Bazel:

bazel run //rust/formatjs_cli:formatjs -- --help

Multi-Platform Build (Darwin ARM64 + Linux x64)

Build for both Darwin ARM64 and Linux x64:

cd rust/formatjs_cli
./build-multiplatform.sh

This will create binaries in dist/formatjs_cli/:

• formatjs-darwin-arm64 - macOS Apple Silicon binary
• formatjs-linux-x86_64 - Linux x86_64 binary

You can also build for specific platforms using Bazel directly:

# Build for Darwin ARM64 (macOS Apple Silicon)
bazel build --platforms=//rust/formatjs_cli/platforms:darwin_arm64 //rust/formatjs_cli:formatjs_cli

# Build for Linux x64
bazel build --platforms=//rust/formatjs_cli/platforms:linux_x86_64 //rust/formatjs_cli:formatjs_cli

Using Cargo

Build and install using Cargo (host platform only):

cd rust/formatjs_cli
cargo build --release
cargo install --path .

Usage

Extract Command

Extract string messages from React components that use react-intl:

formatjs extract "src/**/*.tsx" --out-file messages.json

Full example with options:

formatjs extract "src/**/*.{js,ts,tsx}" \
  --out-file extracted.json \
  --id-interpolation-pattern '[sha512:contenthash:base64:6]' \
  --additional-function-names t,__ \
  --flatten \
  --extract-source-location

Options:

• [FILES]... - File glob patterns to extract from (e.g., src/**/*.tsx)
• --format <PATH> - Path to formatter file controlling JSON output shape
• --in-file <PATH> - File containing list of files to extract (one per line)
• --out-file <PATH> - Target file for aggregated .json output
• --id-interpolation-pattern <PATTERN> - Pattern to auto-generate message IDs (default: [sha512:contenthash:base64:6])
• --extract-source-location - Extract metadata about message location in source
• --additional-component-names <NAMES> - Additional component names to extract from (comma-separated)
• --additional-function-names <NAMES> - Additional function names to extract from (comma-separated)
• --ignore <PATTERNS> - Glob patterns to exclude
• --throws - Throw exception when failing to process any file
• --pragma <PRAGMA> - Parse custom pragma for file metadata (e.g., @intl-meta)
• --preserve-whitespace - Preserve whitespace and newlines
• --flatten - Hoist selectors and flatten sentences

Compile Command

Compile extracted translation files into react-intl consumable JSON:

formatjs compile "lang/*.json" --out-file compiled.json

Full example with options:

formatjs compile "lang/*.json" \
  --out-file compiled.json \
  --ast \
  --pseudo-locale en-XA

Options:

• [TRANSLATION_FILES]... - Glob patterns for translation files (e.g., foo/**/en.json)
• --format <PATH> - Path to formatter file that converts input to Record<string, string>
• --out-file <PATH> - Output file path (prints to stdout if not provided)
• --ast - Compile to AST instead of strings
• --skip-errors - Continue compiling after errors (excludes keys with errors)
• --pseudo-locale <LOCALE> - Generate pseudo-locale files (requires --ast)
  • Values: xx-LS, xx-AC, xx-HA, en-XA, en-XB
• --ignore-tag - Treat HTML/XML tags as string literals

Compile-Folder Command

Batch compile all translation JSON files in a folder:

formatjs compile-folder lang/ dist/lang/

Full example with options:

formatjs compile-folder lang/ dist/lang/ --ast

Options:

• <FOLDER> - Source directory containing translation JSON files
• <OUT_FOLDER> - Output directory for compiled files
• --format <PATH> - Path to formatter file
• --ast - Compile to AST

Verify Command

Run checks on translation files to validate correctness:

formatjs verify "lang/*.json" --source-locale en --missing-keys

Full example with all checks:

formatjs verify "lang/*.json" \
  --source-locale en \
  --missing-keys \
  --extra-keys \
  --structural-equality

Options:

• [TRANSLATION_FILES]... - Glob patterns for translation files
• --source-locale <LOCALE> - Required for checks to work (e.g., en)
• --ignore <PATTERNS> - Glob patterns to ignore
• --missing-keys - Check for missing keys in target locales
• --extra-keys - Check for extra keys not in source locale
• --structural-equality - Check structural equality of messages

Development

Running Tests

Using Bazel:

bazel test //rust/formatjs_cli:formatjs_cli_test

Using Cargo:

cargo test

Project Structure

rust/formatjs_cli/
├── Cargo.toml          # Cargo package manifest
├── BUILD.bazel         # Bazel build configuration
├── README.md           # This file
└── src/
    └── main.rs         # Main CLI implementation

Dependencies

• clap: Command-line argument parsing
• anyhow: Error handling
• serde & serde_json: JSON serialization
• formatjs_icu_messageformat_parser: ICU MessageFormat parsing
• formatjs_icu_skeleton_parser: ICU skeleton parsing

Performance

This Rust implementation provides significant performance improvements over the Node.js-based CLI, especially for:

• Large codebases: 10-100x faster extraction and compilation
• Batch processing: Minimal overhead when processing many files
• CI/CD pipelines: Faster builds and deployments
• Memory efficiency: Lower memory usage for large message catalogs

See the benchmarks for detailed performance comparisons.

Contributing

Contributions are welcome! Please see the main FormatJS repository for contribution guidelines.

License

MIT

Related Packages

• @formatjs/cli - Node.js-based CLI
• formatjs_icu_messageformat_parser - ICU MessageFormat parser
• formatjs_icu_skeleton_parser - ICU skeleton parser