or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdmessage-processing.md
tile.json

tessl/npm-babel-plugin-formatjs

Extracts string messages for translation from modules that use formatjs.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/babel-plugin-formatjs@10.5.x

To install, run

npx @tessl/cli install tessl/npm-babel-plugin-formatjs@10.5.0

index.mddocs/

babel-plugin-formatjs

babel-plugin-formatjs is a Babel plugin that extracts string messages for translation from modules that use React Intl. It processes message descriptors from defineMessages(), defineMessage(), intl.formatMessage(), and <FormattedMessage> JSX components, validating ICU message syntax and optimizing bundle size through configurable ID generation and metadata removal.

Package Information

  • Package Name: babel-plugin-formatjs
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install babel-plugin-formatjs

Core Imports

import plugin, { ExtractionResult, DEFAULT_ID_INTERPOLATION_PATTERN } from "babel-plugin-formatjs";

For CommonJS:

const plugin = require("babel-plugin-formatjs");
const { ExtractionResult, DEFAULT_ID_INTERPOLATION_PATTERN } = require("babel-plugin-formatjs");

Note: Type definitions for Options, MessageDescriptor, etc. are available through TypeScript declaration files when using TypeScript, but are not runtime exports.

Basic Usage

Babel Configuration

// babel.config.js
module.exports = {
  plugins: [
    ["babel-plugin-formatjs", {
      // Extract messages to callback
      onMsgExtracted: (filename, messages) => {
        console.log(`Found ${messages.length} messages in ${filename}`);
      },
      // Generate IDs automatically
      idInterpolationPattern: "[sha512:contenthash:base64:6]",
      // Remove descriptions to reduce bundle size
      removeDefaultMessage: false
    }]
  ]
};

Input Code

import { defineMessages, FormattedMessage } from 'react-intl';

const messages = defineMessages({
  greeting: {
    id: 'app.greeting',
    defaultMessage: 'Hello {name}!',
    description: 'Greeting message for user'
  }
});

function MyComponent({ name }) {
  return (
    <FormattedMessage
      id="app.welcome"
      defaultMessage="Welcome to our app!"
      description="Welcome message"
    />
  );
}

Output

import { defineMessages, FormattedMessage } from 'react-intl';

const messages = defineMessages({
  greeting: {
    id: 'app.greeting',
    defaultMessage: 'Hello {name}!'
  }
});

function MyComponent({ name }) {
  return (
    <FormattedMessage
      id="app.welcome"
      defaultMessage="Welcome to our app!"
    />
  );
}

Architecture

babel-plugin-formatjs is built around several core components:

  • Main Plugin: Babel plugin function that orchestrates the transformation process
  • Visitor Pattern: Two specialized visitors handle different AST node types (CallExpression and JSXOpeningElement)
  • Message Processing: Utilities for extracting, validating, and transforming message descriptors
  • Configuration System: Comprehensive options for customizing extraction behavior
  • ICU Validation: Integration with ICU MessageFormat parser for syntax validation

Capabilities

Plugin Configuration

Core plugin setup and configuration options for customizing extraction behavior, ID generation, and output processing.

declare const plugin: (
  api: object,
  options: Options | null | undefined,
  dirname: string
) => PluginObj<PluginPass>;

interface Options {
  overrideIdFn?: (
    id?: string,
    defaultMessage?: string,
    description?: string,
    filePath?: string
  ) => string;
  onMsgExtracted?: (filePath: string, msgs: MessageDescriptor[]) => void;
  onMetaExtracted?: (filePath: string, meta: Record<string, string>) => void;
  idInterpolationPattern?: string;
  removeDefaultMessage?: boolean;
  additionalComponentNames?: string[];
  additionalFunctionNames?: string[];
  pragma?: string;
  extractSourceLocation?: boolean;
  ast?: boolean;
  preserveWhitespace?: boolean;
}

Plugin Configuration

Message Processing

Core message descriptor interfaces and processing utilities for handling React Intl message extraction and transformation.

interface MessageDescriptor {
  id: string;
  defaultMessage?: string;
  description?: string;
}

interface ExtractedMessageDescriptor extends MessageDescriptor {
  file?: string;
  start?: number;
  end?: number;
  line?: number;
  column?: number;
}

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

Message Processing

Core Types

interface MessageDescriptor {
  id: string;
  defaultMessage?: string;
  description?: string;
}

interface ExtractedMessageDescriptor extends MessageDescriptor {
  file?: string;
  start?: number;
  end?: number;
  line?: number;
  column?: number;
}

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

interface Options {
  overrideIdFn?: (
    id?: string,
    defaultMessage?: string,
    description?: string,
    filePath?: string
  ) => string;
  onMsgExtracted?: (filePath: string, msgs: MessageDescriptor[]) => void;
  onMetaExtracted?: (filePath: string, meta: Record<string, string>) => void;
  idInterpolationPattern?: string;
  removeDefaultMessage?: boolean;
  additionalComponentNames?: string[];
  additionalFunctionNames?: string[];
  pragma?: string;
  extractSourceLocation?: boolean;
  ast?: boolean;
  preserveWhitespace?: boolean;
}

Constants

const DEFAULT_ID_INTERPOLATION_PATTERN: string = "[sha512:contenthash:base64:6]";