LocalizationManager class

Engine-wide localization service.

Manages locale loading, key lookup, variable interpolation, and plural selection for all engine subsystems and game code.


Setup

final l10n = LocalizationManager();

// Load namespaced JSON asset files
await l10n.load(const Locale('en'), 'assets/l10n/ui_en.json',   ns: 'ui');
await l10n.load(const Locale('en'), 'assets/l10n/game_en.json', ns: 'game');
await l10n.load(const Locale('fr'), 'assets/l10n/ui_fr.json',   ns: 'ui');
await l10n.load(const Locale('fr'), 'assets/l10n/game_fr.json', ns: 'game');

l10n.setLocale(const Locale('fr'));

print(l10n.t('ui.start_game'));               // Commencer
print(l10n.t('game.enemies.count', {'count': 3})); // 3 ennemis

The engine's manager

// On app / engine init:
engine.context.localization = l10n;

// In game code with the engine at hand:
final text = engine.context.localization!.t('ui.back');

// In widgets under a GameWidget (which provides a LocalizationScope for
// the engine's manager):
final text = LocalizationScope.of(context).t('ui.back');

Fallback chain For any key looked up under locale fr_CA:

  1. fr_CA table
  2. fr table
  3. en table (or whichever fallbackLocale is set to — and its bare language after it, so a fallback of en_US also reads en)
  4. The key itself (so missing keys are obvious in the UI)

A locale with a script keeps its own tables: zh_Hans and zh_Hant do not share one, and zh_Hans_CN falls back to zh_Hans, then zh.


JSON file format — flat or nested, auto-flattened with . notation:

{
  "ui": {
    "start_game": "Start Game",
    "back": "Back"
  },
  "game.hp.label": "HP",
  "item.count": "{count, plural, =0{No items} =1{One item} other{{count} items}}"
}

Constructors

LocalizationManager({Locale? fallbackLocale})
A manager with no tables yet and en as its current locale; keys missing from the current locale are looked up in fallbackLocale (en when null).

Properties

currentLocale → Locale
Currently active locale.
no setter
fallbackLocale → Locale
Locale used when a key is missing in the active locale chain.
final
hashCode → int
The hash code for this object.
no setterinherited
localeChanged → Signal<Locale>
Reactive signal — emits the new Locale on every setLocale call.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

dispose() → void
Forgets every table and disposes localeChanged. Not to be used afterwards.
has(String key, {Locale? locale, String? ns}) → bool
Returns true if key is present in the active locale (or fallback).
hasTable(Locale locale, {String? ns}) → bool
Whether strings are registered for exactly locale — in namespace ns, or in any when it is null. The fallback chain is not consulted.
load(Locale locale, String assetPath, {String ns = defaultNamespace, AssetBundle? bundle}) → Future<LocaleStringTable>
Loads a JSON asset file under locale and ns (namespace).
loadAll(List<Locale> locales, String pathTemplate, {String ns = defaultNamespace, AssetBundle? bundle}) → Future<void>
Loads all locales for a list of locales from a path template.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
raw(String key, {Locale? locale, String? ns}) → String?
Returns the raw (uninterpolated) template for key, or null if absent.
register(Locale locale, LocaleStringTable table, {String ns = defaultNamespace}) → void
Registers a pre-built table under locale / ns, merged into what is already there: its keys replace the same keys, the rest stay.
registerMap(Locale locale, Map<String, String> strings, {String ns = defaultNamespace}) → void
Registers a plain Map<String, String> directly.
setLocale(Locale locale) → void
Switches to locale and notifies localeChanged.
t(String key, {Map<String, Object?> args = const {}, Locale? locale, String? ns}) → String
Returns the localized string for key in the active locale.
toString() → String
A string representation of this object.
inherited
tr(String key, Map<String, Object?> args, {Locale? locale, String? ns}) → String
Convenience: looks up key and immediately applies args.

Operators

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

Static Methods

tagOf(Locale locale) → String
The key locale's tables are kept under, and what {locale} in a loadAll path becomes: language, script and country joined by _ — 'en', 'fr_CA', 'zh_Hans', 'zh_Hant_TW'.

Constants

defaultNamespace → const String
Default namespace used when none is specified.
dialogueNamespace → const String
Namespace used by the Narrative subsystem.