BloomI18n class

Reactive internationalization controller and multi-catalog store for Bloom applications.

Manages registered message catalogs, dynamic on-demand catalog loading, fallback resolution, and provides reactive signal state (locale, isLoading) that triggers fine-grained UI re-renders inside Live blocks when the active locale updates.

Reactivity Model

Calling translate or t without an explicit locale argument reads the reactive signal BloomI18n.locale. When evaluated inside a Live component, signals automatically record a dependency on the active locale. When setLocale is called, only components observing the locale update in-place without reloading the page or re-mounting unaffected DOM branches.

Singleton vs Standalone Instances

BloomI18n.instance is the global ambient singleton used by top-level convenience functions (t, setLocale, loadLocale). You can also instantiate standalone BloomI18n(...) instances for isolated sub-applications, headless server rendering, or unit tests.

Fallback Resolution Chain

When a translation key is looked up via translate, BloomI18n resolves templates through:

  1. Exact requested locale catalog (e.g. 'fr-CA')
  2. Base language subtag of requested locale (e.g. 'fr')
  3. Configured defaultLocale catalog (e.g. 'en-US')
  4. Base language subtag of defaultLocale (e.g. 'en')
  5. The raw messageId itself as fallback, triggering the onMissingKey callback if configured.

Lazy Catalog Loading

Translation catalogs can be split and loaded on demand using registerLoader and loadLocale. While a catalog is loading over the network, isLoading is set to true, allowing UI components to render loading indicators or skeletons.

// Register catalogs
BloomI18n.instance.addCatalog(BloomCatalog('en-US', {
  'welcome': 'Welcome to Bloom, {name}!',
}));
BloomI18n.instance.addCatalog(BloomCatalog('fr-FR', {
  'welcome': 'Bienvenue sur Bloom, {name} !',
}));

// Use in a reactive UI component:
BloomNode greeting() => Live(() => Div(
  text: t('welcome', args: {'name': 'Alice'}),
));

// Update locale dynamically:
BloomI18n.instance.setLocale('fr-FR'); // Re-renders greeting() automatically

See also:

  • BloomCatalog, storing ICU message templates for a single locale.
  • t, global shorthand for reactive translations.
  • setLocale, global shorthand for updating the active locale.

Constructors

BloomI18n({String initialLocale = 'en-US', String defaultLocale = 'en-US', Map<String, BloomCatalog>? catalogs, void onMissingKey(String key, String locale)?, LocaleStorage? storage})
Creates a new BloomI18n store instance.

Properties

currentDirection → BloomTextDirection
The text direction of the currently active locale (BloomTextDirection.rtl or BloomTextDirection.ltr).
no setter
currentLocale ↔ String
The active locale string value.
getter/setter pair
defaultLocale → Signal<String>
Fallback locale signal used when a message template is missing in the active locale catalog.
final
hashCode → int
The hash code for this object.
no setterinherited
isCurrentRtl → bool
Whether the currently active locale uses a right-to-left (RTL) script.
no setter
isLoading → Signal<bool>
Reactive signal indicating whether an asynchronous catalog is currently loading via loadLocale.
final
locale → Signal<String>
Reactive signal containing the current active locale tag (e.g. 'en-US').
final
onMissingKey ↔ void Function(String key, String locale)?
Optional callback invoked whenever a translation key is missing across all fallback catalogs.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
storage → LocaleStorage?
Optional storage adapter for persisting user locale choices across sessions.
final
supportedLocales → List<String>
Returns an unmodifiable list of all currently loaded locale tags.
no setter

Methods

addCatalog(BloomCatalog catalog) → void
Registers a pre-constructed BloomCatalog in this store.
addJson(String locale, Map<String, dynamic> json) → void
Adds message templates from a dynamic JSON-compatible map for locale.
addMessages(String locale, Map<String, String> messages) → void
Adds a map of ICU message templates for locale.
getCatalog(String targetLocale) → BloomCatalog?
Returns the registered BloomCatalog for targetLocale, or null if not loaded.
hasLocale(String targetLocale) → bool
Returns true if a catalog is registered or currently loaded for targetLocale.
loadLocale(String targetLocale) → Future<bool>
Asynchronously loads the catalog for targetLocale using a registered loader.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
registerLoader(String locale, Future<BloomCatalog> loader()) → void
Registers an asynchronous catalog loader function for locale.
setLocale(String newLocale) → void
Changes the active locale to newLocale, updates the reactive locale signal, and persists to storage.
t(String messageId, {Map<String, Object>? args, String? locale}) → String
Shorthand alias for translate.
toString() → String
A string representation of this object.
inherited
translate(String messageId, {Map<String, Object>? args, String? locale}) → String
Translates messageId for targetLocale (or active locale if omitted), substituting args.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

instance → BloomI18n
Global singleton instance of BloomI18n.
final