fluent_bundle library
Runtime API for Project Fluent.
Most apps need only this barrel: construct a FluentBundle, call
FluentBundle.addResource with the FTL source, then resolve messages
via FluentBundle.formatMessage or FluentBundle.formatPattern.
NUMBER and DATETIME are always available. A bare FluentBundle('en')
uses the spec-fallback FluentBackend — digit-correct but locale-blind,
plurals always other. For CLDR-aware output pass a backend::
IntlBackendfrompackage:fluent_intl—package:intl; the lighter setup, real cardinal plurals for every locale.IcuBackendfrompackage:fluent_icu— ICU4X; full ECMA-402, all-locale ordinals, calendars, numbering systems, units.
Write your own by extending FluentBackend and overriding any subset
of its methods; the base is always the spec fallback.
Tools that walk the parse-time AST import
package:fluent_bundle/syntax.dart. Inline <bold> / <a> markup
rendered to a span tree lives in package:fluent_bundle/markup.dart.
Classes
- CompiledMessage
-
A compiled message. The value is null when the source message had
only attributes (e.g.
email = .label = X), in which case attributes are the only callable surface. - CompiledPattern
- A compiled pattern. Either a plain string (when there are no placeables) or a list of elements to evaluate at format time.
- FluentBackend
- Everything locale-aware the resolver needs: how to format a number, how to format a date, and which plural category a number falls into.
- FluentBundle
- A localization bundle: a set of compiled messages and terms in one locale (or ordered locale fallback chain), plus the functions that expressions may call.
- FluentBundleChain
- An ordered locale-fallback chain of bundles that IS a FluentBundle.
- FluentDateTime
- A wall-clock instant plus its formatting options.
- FluentDateTimeOptions
-
Options accepted by FluentDateTime and the
DATETIME()builtin. - FluentFormatContext
-
The per-format-call context handed to a FluentBackend, to
FluentValue.format, and to user-supplied functions. - FluentNone
- A fallback value returned when resolution can't produce a real one (missing variable, unknown reference, uncoerceable host value).
- FluentNumber
- A numeric value plus its formatting options.
- FluentNumberOptions
-
Options accepted by FluentNumber and the
NUMBER()builtin. - FluentString
-
A locale-independent string. Used for string literals (
"hello") and for any host-languageStringargument the bundle receives. - FluentValue
- The runtime representation of any value Fluent can format or compare.
- LoadResult
- Result of FluentBundle.addResource.
Enums
- PluralCategory
-
CLDR plural categories. The order is fixed by Unicode; a select
expression matches a numeric selector against the identifier key of a
variant (
one,other, …) by asking the bundle'sFluentBackendfor the value's category. - PluralRuleType
- Which CLDR plural-rule table a selection consults.
Functions
-
isValidCurrencyCode(
String? code) → bool -
Whether
codeis a well-formed ISO 4217 alphabetic currency code. The shared half of the currency guard — a backend seeingstyle: currencywith an invalid code records FluentTypeError.invalidCurrencyCode and renders decimal instead. -
negotiateLocale(
String requested, {required List< String> available}) → String? -
The single best available match for
requested, or null when nothing inavailablematches. The first element of negotiateLocaleChain for one requested tag, without a fallback. -
negotiateLocaleChain(
{required List< String> requested, required List<String> available, String? fallback}) → List<String> -
The ordered locale fallback chain for
requestedagainstavailable.
Typedefs
-
FluentFunction
= FluentValue Function(List<
FluentValue> positional, Map<String, FluentValue> named, FluentFormatContext context) -
A Fluent built-in or user-supplied callable (e.g.
NUMBER,DATETIME, or a customRELATIVE()).
Exceptions / Errors
- CallbackParseError
- A spec error raised mid-production with its own code.
- ExpectedCharRangeError
- E0004 — a character in a specific range was expected.
- ExpectedMessageFieldError
- E0005 — a message needs a value or attributes.
- ExpectedTermFieldError
- E0006 — a term needs a value.
- ExpectedTokenError
-
E0003 — a specific token was expected (
=,}, …). - FluentArgumentError
- Caller-provided value can't be coerced into a FluentValue.
- FluentCyclicReferenceError
- A pattern referenced itself transitively (cycle detected via Scope.dirty).
- FluentError
- A runtime error during Fluent message resolution.
- FluentFormatError
- A backend could not honor a formatting request under the current locale chain — an unsupported option, missing locale data, or an invalid option value. The value still rendered (via a fallback); this records what could not be done so it surfaces during dev.
- FluentOverrideError
-
addResourcetried to redefine an existing message or term whileallowOverrideswas false. The existing definition wins; this records the conflict. - FluentParseError
- A failure during Fluent Syntax parsing.
- FluentReferenceError
- A reference to an entity (message, term, attribute, variable, function) that does not exist in the bundle.
- FluentResolutionLimitError
-
The bundle hit
MAX_PLACEABLES(Billion Laughs / Quadratic Blowup guard). - FluentTypeError
- A built-in function received an argument of an incompatible type.
- InvalidUnicodeEscapeSequenceError
-
E0026 — a malformed
\\uXXXX/\\UXXXXXXescape. - UnbalancedClosingBraceError
-
E0027 — a
}with no matching{. - UnknownEscapeSequenceError
- E0025 — a backslash escape the spec doesn't define.
- UnterminatedStringError
- E0020 — a string literal ran to end of line unterminated.