Message Compilation

/**
 * 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 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;
}

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

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
});

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'
});

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
});

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);
}

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
});

# 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

# 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

# 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

/**
 * 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]

# 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

# 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

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

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

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

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