Fluent Core Architecture

fluent-core-architecture

Quick Reference

Fluent Package Ecosystem

Runtime Model (data flow)

FTL string ──► FluentResource ──► FluentBundle ──► getMessage(id) ──► formatPattern(pattern, args) ──► string
                  (parse)           (store)          (lookup)              (resolve + format)

Key Terminology

Critical Warnings

NEVER confuse Fluent with ICU MessageFormat. They are fundamentally different systems. Fluent uses asymmetric localization (each locale develops independently); ICU uses symmetric patterns (source language grammar leaks to all translations). See the comparison table below.

NEVER use @fluent/syntax for runtime message formatting. It is a tooling library for linting, AST manipulation, and codegen. ALWAYS use @fluent/bundle for runtime formatting.

NEVER skip the two-step lookup: ALWAYS call getMessage(id) first, then formatPattern(pattern, args). There is no single-call format method.

NEVER pass raw FTL strings to addResource(). It requires a FluentResource instance: bundle.addResource(new FluentResource(ftl)).

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

Design Philosophy

Project Fluent is Mozilla's localization system built on one core principle: asymmetric localization. Translators can use the full expressive power of their language without asking developers for permission.

Asymmetric Localization

Traditional i18n systems (gettext, Java properties, ICU MessageFormat) enforce a one-to-one mapping between source strings and translations. The grammar of the source language limits what translators can express. Fluent eliminates this constraint:

• A simple English string can map to a complex multi-variant Polish translation with grammatical cases.
• The Polish translator adds selectors independently -- no code changes, no English file modifications.
• Locale-specific logic is isolated. Complexity in one locale NEVER leaks to another.

Progressive Enhancement

Each locale develops independently. English may use welcome = Welcome, { $name }! while Polish uses a selector on grammatical gender. The developer writes one getMessage("welcome") call. Fluent handles the rest.

Simplicity for Simple Cases

The basic syntax is as simple as any properties file:

hello = Hello, world!

Complexity (selectors, terms, attributes) is added only when a locale needs it.

FTL Format Overview

FTL (Fluent Translation List) is the file format for Fluent translations. Syntax version: Fluent Syntax 1.0 (released April 2019).

Messages

The basic unit of translation. An identifier, =, and a value (pattern):

hello = Hello, world!
welcome = Welcome, { $name }!

Terms

Reusable fragments prefixed with -. ALWAYS use terms for brand names and shared vocabulary:

-brand-name = Firefox
about = About { -brand-name }.

Terms accept parameters and can store grammatical metadata as attributes. Terms are NEVER accessible via the public getMessage() API.

Attributes

Multiple translatable strings grouped under one message using .attribute syntax:

login-input = Predefined value
    .placeholder = email@example.com
    .aria-label = Login input value

Selectors

Choose translation variants based on runtime values. Every select expression MUST have exactly one default variant (marked with *):

emails =
    { $count ->
        [one] You have one unread email.
       *[other] You have { $count } unread emails.
    }

Comments

Three levels: # (message-bound), ## (section group), ### (file-level resource comment).

The Runtime Model

FluentBundle -> FluentResource -> Message -> Pattern -> formatPattern

The runtime model follows a strict pipeline:

Step 1: Create a bundle for a specific locale:

import { FluentBundle, FluentResource } from "@fluent/bundle";
const bundle = new FluentBundle("en-US");

Step 2: Parse FTL into a resource and add it to the bundle:

const resource = new FluentResource(`
welcome = Welcome, { $name }!
-brand = Acme Corp
`);
const errors = bundle.addResource(resource);

Step 3: Look up a message by its identifier:

const msg = bundle.getMessage("welcome");

The returned Message object has this shape:

interface Message {
  value: Pattern | null;
  attributes: Record<string, Pattern>;
}

Step 4: Format the pattern with runtime arguments:

if (msg?.value) {
  const text = bundle.formatPattern(msg.value, { name: "Anna" });
  // -> "Welcome, Anna!"
}

Key API Methods

Constructor Options

Fluent vs ICU MessageFormat

The most significant difference: in ICU, if Polish needs grammatical cases, the developer MUST modify source code to pass case parameters and update the English source string. In Fluent, the Polish translator adds a selector independently -- the English file stays simple and no code changes are needed.

Decision Tree: Which Package Do I Need?

Need to format messages at runtime in an app?
├── YES -> @fluent/bundle (core runtime)
│   ├── Building a React app? -> ALSO add @fluent/react
│   └── Need locale negotiation? -> ALSO add @fluent/langneg
└── NO
    ├── Linting or validating FTL files? -> @fluent/syntax
    ├── Programmatically generating FTL? -> @fluent/syntax
    └── Building editor tooling? -> @fluent/syntax

NEVER use @fluent/syntax for runtime formatting. It produces a full AST and is significantly heavier than the optimized runtime parser in @fluent/bundle.

Reference Links

• references/methods.md -- Key types: FluentBundle, FluentResource, Message, Pattern
• references/examples.md -- Full FTL + TypeScript flow examples
• references/anti-patterns.md -- Common mistakes including ICU confusion

Official Sources

• https://projectfluent.org -- Design philosophy, syntax guide
• https://github.com/projectfluent/fluent.js -- JavaScript implementation
• https://github.com/projectfluent/fluent -- FTL specification and EBNF grammar
• https://raw.githubusercontent.com/projectfluent/fluent/master/spec/fluent.ebnf -- Formal grammar