Fluent Core Bundle API

fluent-core-bundle-api

Quick Reference

FluentBundle Method Signatures

Constructor Options

FluentType Hierarchy

FluentVariable Accepted Types

Critical Warnings

NEVER pass a raw string to addResource() -- it expects a FluentResource instance. ALWAYS wrap FTL strings: bundle.addResource(new FluentResource(ftlSource)).

ALWAYS use the two-step pattern: call getMessage() first, then formatPattern() on its value. There is no single-call format() method (removed in v0.14.0).

ALWAYS check msg.value for null before formatting -- messages with only attributes have value: null. Formatting null causes a runtime error.

ALWAYS pass an errors array to formatPattern() in production code. Without it, the method throws on the first resolution error instead of returning a best-effort string.

NEVER access terms via getMessage("-term-name") -- this returns undefined. Terms are resolved automatically when referenced inside messages.

NEVER pass objects, arrays, or booleans as variables -- only string, number, Date, FluentType, and TemporalObject are valid FluentVariable types.

Core Pattern: Two-Step Message Formatting

Every message formatting operation in Fluent follows this mandatory two-step pattern:

import { FluentBundle, FluentResource } from "@fluent/bundle";

// Step 0: Create bundle and load resource
const bundle = new FluentBundle("en-US");
const errors = bundle.addResource(new FluentResource(`
welcome = Welcome, {$name}!
login-input =
    .placeholder = Email address
    .aria-label = Login input
`));

// Step 1: Retrieve the message
const msg = bundle.getMessage("welcome");

// Step 2: Format the pattern (with error collection)
if (msg?.value) {
  const errs: Error[] = [];
  const text = bundle.formatPattern(msg.value, { name: "Anna" }, errs);
  // text === "Welcome, Anna!"
}

For attribute-only messages, access attributes directly:

const loginMsg = bundle.getMessage("login-input");
if (loginMsg) {
  // loginMsg.value is null -- this message has no value
  const placeholder = bundle.formatPattern(loginMsg.attributes["placeholder"]);
  // placeholder === "Email address"
}

Error Handling Modes

Mode 1: Silent Collection (Production)

const errors: Error[] = [];
const text = bundle.formatPattern(pattern, args, errors);
// Returns best-effort string with {???} for failed parts
// errors array contains all resolution issues

Mode 2: Throw on First Error (Development)

// No errors array -- throws ReferenceError, TypeError, or RangeError
const text = bundle.formatPattern(pattern, args);

Error Types Diagnostic Table

Parse-Time vs. Resolution-Time Errors

• Parse-time (addResource() return value): FTL syntax errors. Per-message -- one bad message does not block others.
• Resolution-time (formatPattern() errors): Missing variables, broken references, type mismatches. Occur when formatting a specific pattern.

Decision Tree: Choosing Error Handling Mode

Is this production code?
├── YES → ALWAYS pass errors array to formatPattern()
│         Log errors for monitoring, display best-effort text to users
└── NO (development/testing)
    ├── Want to catch errors early? → Omit errors array (throws)
    └── Want to see fallback behavior? → Pass errors array

Decision Tree: FluentResource vs. @fluent/syntax

What do you need?
├── Runtime message formatting → @fluent/bundle (FluentResource)
│   Optimized parser, small bundle, fast
├── FTL linting or validation → @fluent/syntax (FluentParser)
│   Full AST with spans, strict parsing
├── Programmatic FTL generation → @fluent/syntax (FluentSerializer)
│   Round-trip parse/serialize
└── Editor tooling → @fluent/syntax
    Span information for highlights, completions

Decision Tree: Bundle Constructor Options

Setting up FluentBundle options?
├── useIsolating
│   ├── Mixed RTL/LTR content (e.g., Arabic UI with English names)
│   │   → ALWAYS keep true (default)
│   ├── Single-direction content only
│   │   → Safe to set false
│   └── Testing (Unicode marks interfere with assertions)
│       → Set false for test bundles only
├── functions
│   ├── Need custom formatting beyond NUMBER/DATETIME?
│   │   → Register in constructor: { functions: { MY_FUNC: ... } }
│   └── Built-in NUMBER and DATETIME sufficient?
│       → No configuration needed
└── transform
    ├── Need to sanitize or escape all text elements?
    │   → Provide transform function
    └── No text transformation needed?
        → Use default identity transform

Custom Functions

ALWAYS register custom functions in the constructor. Functions receive two arguments: positional values and named options.

const bundle = new FluentBundle("en-US", {
  functions: {
    UPCASE: (positional: FluentValue[], named: Record<string, FluentValue>) => {
      const val = positional[0];
      return typeof val === "string" ? val.toUpperCase() : String(val).toUpperCase();
    },
  },
});

Corresponding FTL:

shout = { UPCASE($name) }

Built-in Functions

FTL usage:

price = Total: { NUMBER($amount, minimumFractionDigits: 2) }
event-date = { DATETIME($date, dateStyle: "long") }

FluentResource

FluentResource parses an FTL string into an optimized runtime representation. It uses a purpose-built parser that is smaller and faster than @fluent/syntax.

const resource = new FluentResource(`
hello = Hello, world!
welcome = Welcome, {$name}!
-brand = Acme Corp
`);
// resource.body.length === 3 (2 messages + 1 term)

Key characteristics:

• Parsing errors are per-message -- one bad message does not prevent others from being parsed
• ALWAYS use the constructor directly. FluentResource.fromString() was removed in v0.14.0
• For strict FTL validation, use @fluent/syntax instead

Reference Links

• references/methods.md -- Complete API signatures for FluentBundle, FluentResource, FluentType hierarchy
• references/examples.md -- Working code examples for bundle creation, formatting, error handling, custom functions
• references/anti-patterns.md -- All 10 API anti-patterns with corrections

Official Sources

• https://github.com/projectfluent/fluent.js/tree/main/fluent-bundle
• https://github.com/projectfluent/fluent.js/blob/main/fluent-bundle/src/bundle.ts
• https://github.com/projectfluent/fluent.js/blob/main/fluent-bundle/src/resolver.ts
• https://github.com/projectfluent/fluent.js/blob/main/fluent-bundle/src/builtins.ts
• https://github.com/projectfluent/fluent.js/blob/main/fluent-bundle/CHANGELOG.md